Authentication

ET-Client-Name Header

Most APIs are open under Norwegian Licence for Open Government Data (NLOD), however, it is required that all consumers identify themselves by using the header ET-Client-Name.

Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers. The structure of ET-Client-Name should be: "<company>-<application>".

Header examples:

Credentials

The use of Entur's privileged endpoints requires authentication. Entur's APIs use OAuth2 authentication, with the Client Credentials Grant (https://oauth.net/2/grant-types/client-credentials/).

This works by exchanging a client ID and a client secret for an access token which is included in the header for API requests.

Authentication Flow

Entur uses OAuth2 as the authentication protocol, and the Client Credentials grant as authentication flow for non-interactive authentication. Client Credentials grant works by exchanging a client ID and a client secret provided by Entur for an access token from the authentication service.

The access token is a JWT (which will be covered in detail later) and is included in the HTTP Authentication header by the application sending requests to Entur's APIs. The token is validated on every request, and an invalid token will result in a rejected request.

The following illustration is a high level description of the authentication flow:

Illustration 1.1: Authentication flow

1. The application sends an authentication request with a "client_id" and "client_secret" to the Authentication Service (AS).
2. The Authentication Service (AS) validates the credentials and returns an access token.
3. The application includes the access token in the request header to the Entur APIs.
4. The APIs validates the access token, executes the action and/or returns the requested information.

Obtaining a Token

To obtain a token you need to send an authentication request to the authentication endpoint: https://<AUTHENTICATION SERVICE HOST>/oauth/token. In addition to a valid client ID and client secret, the request must include a valid Audience value.

Authentication server and audience available for Partners:

Dev and Staging consist of data which is used for testing.

The following example shows how an access token can be obtained by using the provided information and the curl command:

curl --request POST \
  --url https://partner.entur.org/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id":" Q2xpZW50X0lE ",
    "client_secret": 🤫,
    "audience":"https://api.entur.io",
    "grant_type":"client_credentials"
  }

There are several libraries available for authenticating your application, including our own Enturs JWT-client. We highly recommend using a library for your intended language and framework instead of authenticating manually.

The Access Token

The access tokens used by Entur are JWTs (https://jwt.io/introduction/), which are Base64-encoded, signed self-contained documents consisting of three parts: A header, payload and cryptocraphic signature to verify the validity and integrity of the token. The access token contains all necessary information to authenticate your application for Entur's APIs.

For more information, check out https://auth0.com/docs/tokens/reference/jwt/jwt-structure.

Caching

Access tokens are stateless documents, meaning they can be used for multiple requests and in parallel if needed. It's neither necessary nor efficient to re-authenticate for every API request. You're required to cache the access token, in memory or through a secure storage mechanism to avoid needless re-authentication.

Failure to do so might lead to authentication requests being throttled or worst case having your client blocked/disabled.

Using Access Tokens in Requests

After obtaining the access token (JWT), add it to the Authorization HTTP header in subsequent requests to the APIs:

Authorization: Bearer <JWT token>​

For example

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Entur's APIs then validate the access token signature and grant the corresponding access.

Expiry and re-authentication

Access tokens have longevity but will expire after a certain amount of time. If the token has expired, API calls will return HTTP status 401. Keep track of the remaining time using the expires_in sibling field returned by the client credentials call, or by checking the exp claim/value in the payload section of the JWT.

We recommend that some time (a few (10) seconds, ideally the time it takes to make the call) is left on the token when invoking requests. Your implementation should NOT wait for 401 responses before refreshing the token, as this will spam our logs (and potentially make a bit of thread spagetti in your backend).

HTTP Error Messages

These error messages are from the APIs.

• 301: Moved Permanently - The HTTP server was been moved permanently to a HTTPS server. This error is used for permanent URL redirection.
• 302: Redirect - Attempts to connect to the Entur APIs with HTTP will end in a redirection. Make sure your server is HTTPS.
• 401: Unauthorized - The request is lacking valid authentication. This may indicate that the “client_secret” has been changed or is not correct.
• 403: Forbidden - If the scope claim does not include a request your application is trying to acces you will get this error. This may indicate that your application is wrongly configured or that you do not have the permissions needed for making changes to the specific endpoint. Ref. https://auth0.com/docs/api-auth/tutorials/verify-access-token#validate-t... (“How can I check the permissions?”).
• 405: Method not allowed - This might mean that your BFF is trying to connect to the server via HTTP, which the Entur API does not support.
• 408: Session timeout - The access token has expired while the session was ongoing. Reauthenticate the session and remember to check when the access token expires.

Troubleshooting

These errors are coming from the authentication service.

“Invalid grant” - This is a generic error message and may mean one of the following:

• Wrong username and/or password
• Username is from an invalid domain
• Endpoint does not support “Resource Owner Password Credentials Grant”. Validate that you are using the “client_id” correctly.

“Unauthorized client” - See “401: Unathorized”:

• “client_secret” might have been changed. Check if it is the same.

Reference List

• https://auth0.com/docs/api-auth/tutorials/verify-access-token#validate-the-claims
• https://auth0.com/docs/tokens/use-access-tokens
• https://auth0.com/docs/security/store-tokens
• https://tools.ietf.org/html/draft-ietf-oauth-security-topics-11
• https://jwt.io/introduction/
• https://auth0.com/docs/api-auth/tutorials/verify-access-token#sample-implementation