Authentication
Both our Open and Partner services require clients to first be authenticated to use them. The exact method of authentication will differ depending on the type of service used. However, only our Partner services may require granting the clients additional permissions to use them. In the sections that follow, we go into more detail on how you can authenticate against the different type of service APIs we provide.
Open Services
Our Open Service APIs are licensed under the Norwegian License for Open Government Data (NLOD). If you desire to consume these services, you must authenticate all HTTP requests you make against the APIs using the ET-Client-Name header. The value of this header should be unique, and identify your individual company and application. The desired format of the value is <company>-<application> with no capital letters.
Header Example:
If your company is called "Forsen Utvikling" and the application you are developing is named "Infoplakat", the ET-Client-Name header value would be forsen_utvikling-infoplakat.
Curl Example:
Code
We employ strict rate-limiting and blocking policies against API consumers who not do identify themselves using a ET-Client-Name against our Open Services. The header is a requirement and not optional.
For more information, read the following articles:
Partner Services
Our Partner Service APIS rely on OAuth2 as the authentication protocol. Therefore, to call our Partner APIs, you will first need a set of client credentials. To generate these credentials, you must first be onboarded as a Partner and login to the Entur Partner Portal. After logging in, go to the clients overview and press the "New" button*. Leave role assignments for later and fill out all required fields before pressing save. Take note of the presented Client ID and Secret and save them somewhere secure (like a password manager); these are your client credentials. You can exchange these long-lived credentials for shorter-lived JWT access tokens through Entur's Authentication Service. It is the latter tokens that must be sent alongside your Partner API requests in the Authorization HTTP header to authenticate your client.
[!NOTE]
Note that only users with the "Klientadministrator" role in the organization will have the necessary permissions to create new clients. If no one in your organization has the necessary permissions to create new clients, please contact your partner manager and ask them to assign a user in your organization with the role.
For more information, read the following articles:
Access Token Generation (Client Credential Exchange)
To exchange your client credentials for short-lived JWT access tokens, call the authentication service endpoint matching the Partner Portal environment the client was created. The Client ID and Secret must be included as client_id and client_secretfields in the request's json body alongside an audience and grant_type. The appropriate value mappings for each environment can be seen in the table below:
| Environment | Authentication Service Endpoint | Audience | Grant Type |
|---|---|---|---|
| Dev | https://partner.dev.entur.org | https://api.dev.entur.io | client_credentials |
| Staging | https://partner.staging.entur.org | https://api.staging.entur.io | client_credentials |
| Production | https://partner.entur.org | https://api.entur.io | client_credentials |
We highly recommend using existing public SDKs and libraries to handle the client credential exchange flow instead of doing it manually. However, this decision remains up to you.
Json Body Example:
Code
Curl Example
Code
Access Token Caching
After exchanging your client credentials for an access token, you should ensure that it is cached throughout its entire lifetime. When calling the Partner API, this cached token can then be reused instead of having to perform a new client credential exchange against Entur's Authentication Service to generate a new token each time. Do make sure that the storage mechanism used for the caching is secure.
Failing to cache access tokens might result in your client's requests being throttled and/or blocked.
Access Token Usage
The generated access token (JWT) should be included in every request you make towards the Partner Service APIs. Do this by setting your request's HTTP Authorization header value. The format of the value should be Bearer <JWT access token>.
Header Example:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30
Curl Example:
Code
For more information, read the following articles:
Access Token Permissions
Most of Entur's Partner Service APIs will require additional permissions to be assigned to the access token's client before they can be used. This can be done in Entur's Partner portal at the same location where the client was originally generated. For a more detailed explanation on how authorisation generally works for our Partner Service APIs, as well as how to delegate roles and permissions to clients, please refer to the Authorisation article.
Access Token Expiry
Access tokens generated by Entur's Authentication Service have a set lifetime of 24 hours. That is, 24 hours after being generated they will expire and become useless. Using the expired access token in subsequent Partner API calls will then return a 401 HTTP status code. To prevent this from occurring, you should keep track of the expires_in value returned as part of the client credential exchange, or the exp claim located in the payload section of the access token JWT. To read the latter value you will have to decode the Base64 encoded token.
For more information, read the following articles:
Troubleshooting
If you encounter any problems during authentication, refer to the sections below for troubleshooting.
HTTP Status Codes
401: Unauthorized
This error indicates that request is lacking valid authentication. Typically this occurs when attempting to generate an access token for use with our Partner Services, but the provided client_secret is missing or invalid, or the access token itself has expired.
403: Forbidden
This error indicates that access token used in your request is missing the necessary permissions to call the
408: Session timeout
This error indicates that the access token used against our Partner Service APIs expired during processing. Ensure that you reauthenticate and generate a new access token in a timely manner to prevent this error from occuring.