Principles

The SMARTPORTAL API is based on a REST architecture which makes SMART API predictable and resource oriented. It uses HTTP built-in features, like HTTP authentication, HTTP verbs (GET, POST, PUT, PATCH, DELETE) and HTTP response codes to allow easy access from any programming language via off-the-shelf libraries and tools.

Set up an affiliate application on the SSO

In order to set up an affiliate application on the SSO of the SMARTPORTAL follow these steps:

1 - Register on the SSO

Account Approval

Depending on the settings, you may need to wait for account approval completion.

2 - Go to /oauth/applications and click on 'New'

3 - Fill the application data and submit the form:

Application name
Application oauth callback url

Account Activation

Depending on the settings you need to wait for activation

4 - Copy Client ID and Application Secret into your application and set them as environment variables

SMART_SSO_UID = your_client_id

SMART_SSO_SECRET = your_app_secret

Application Permissions

You can only edit and view your own applications.

Integrate with SMARTSSO

In order to set up an affiliate application on the SSO of the SMARTPORTAL follow these steps:

1 - Send the following request to receive the grant token:

GET /oauth/authorize

AUTHORIZATION PARAMETERS

Param	Type	Description
client_id	string	Your client_ID in SMARTSSO. You can find it here: https://id.smart.telekom-dienste.de/oauth/applications
redirect_uri	string	Redirect URL after the user is signed in. Has to match with the callback URL in SMARTSSO.
response_type	string	code

2 - If the user is NOT logged in SMARTSSO, it will redirect to the user sign in page and ask for credentials. If the user is already logged in this step is skipped.

3 - Redirects back to redirect_uri sent in the request with the following parameters:

PARAMETERS

Param	Type	Description
code	string	Token that will be used in following requests

4 - In order to receive the JWT Token, send the following request:

POST /oauth/token

JWT TOKEN PARAMETERS

Param	Type	Description
client_id	string	Your client_ID in SMARTSSO. You can find it here: https://id.smart.telekom-dienste.de/oauth/applications
client_secret	string	Your client_Secret in SMARTSSO. You can find it here: https://id.smart.telekom-dienste.de/oauth/applications
code	string	Returns code received from the first request
redirect_uri	string	Redirect URL after the user is signed in. Has to match with the callback URL in SMARTSSO.
grant_type	string	Returns authorization_code

5 - The response is a JSON with the following fields:

JSON RESPONSES

Param	Type	Description
access_token	string	JWT representing the logged in resource
token_type	string	"Bearer"
expires_in	integer	Time for expiration for the JWT in seconds
refresh_token	string	Use for requests after the expiration time has passed
scope	string	Possible options: "read", "write"
id	uuid	ID of the logged user
email	string	Email of the logged user
first_name	string	First name of the logged user
last_name	string	Last name of the logged user
role	string	Role of the logged user (ex: “user”, “admin”)

Errors

If you get any errors, please check the Errors section in the end.

Common Error Messages

When a request fails, the API returns an error message describing what went wrong. In this section you can read more about these errors and what are the possible solutions for each case.

Errors in the SSO

1 - Membership error

The message received when a user has no access to the app is the following:

Sie haben noch keinen Zutritt zu APPLICATION_NAME. Bitte wenden Sie sich an smart-portal@telekom.de oder einen Administrator.

In this case, the user is asked to contact the service or an Admin in order to grant him access to the app.

2 - Wrong Client UID

When trying to authenticate via SSO, the Client UID needs to be correctly configured. The message that indicates a wrong UID is the following:

Client-Autorisierung MKIM ist fehlgeschlagen: Unbekannter Client, keine Autorisierung mitgeliefert oder Autorisierungsmethode nicht unterstützt.

The Client UID should be the one provided by Smart SSO.

3 - Wrong Redirect-URI

When trying to authenticate via SSO, the redirect URI needs to be correctly configured. The message that indicates a wrong redirect URI is the following:

Der Redirect-URI in der Anfrage ist ungültig.

In this case, it means that the redirect uri sent does not match with the Callback URL set in the Smart SSO.

4 - Wrong response type or params

When setting the response, the params needs to be correct configured. The message that indicates a wrong type or params is the following:

Der Autorisierungs-Server unterstützt diesen Antwort-Typ nicht.

Remember that the response type should be set to ‘code’. This error message can also appear when you send wrong params in the GET request to ‘/oauth/authorize’.

Important

Remember that all requests should be sent as https.