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:

  • "brakar - journeyplanner"
  • "fosen_utvikling - infoplakat"
  • "norway_bussekspress - reiseplanlegger"

Credentials

To use Enturs privileged endpoints your application needs to be authenticated. The Entur APIs use Oauth2 authentication, specifically the Client Credentials Grant (https://oauth.net/2/grant-types/client-credentials/).

Confidentiality

All Client Credentials (client id + client secret) issued by Entur are intended for Server-to-Server (S2S) communication only. End users must never get hold of the client id and client secret, nor the resulting access-token (see below). Communication must always be over HTTPS.

Authentication Flow

Entur uses OAuth2 as an authentication service (AS), and Client Credentials Grant as authentication flow. Client Credentials Grant allows an application to request an access token using client_id and client_secret provided by Entur. The application uses the access token when it makes requests against Entur APIs (RS). The token is validated on every request to the API, and an invalid token will result in a rejected request. The access token is a JWT and will be covered in details later. The following illustration is a high level description of the authentication flow.

authentication flow chart

Illustration 1.1: Authentication flow

  1. The application sends "client_id" and "client_secret" to the AS - Oauth2.
  2. The AS validates the credentials and returns an access token on successful authentication.
  3. The application includes the access token in the request to Entur API.
  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 request access by authenticating. Here you use https://<AUTHENTICATION SERVICE HOST>/oauth/token. In addition to client-id and client-secret, adding the correct Audience is required.

Authentication server and audience available for Partners:

EnvironmentAuthentication Service HostAudience
Devpartner.dev.entur.orgapi.dev.entur.io
Stagingpartner.staging.entur.orgapi.staging.entur.io
Productionpartner.entur.orgapi.entur.io

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

With the given information, and intention to get an access token to Production, we get:

curl --request POST \
  --url https://partner.entur.org/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id":" Q2xpZW50X0lE ",
    "client_secret": [SUPER 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.

The Access Token

The access token provided from Entur is a JWT (https://jwt.io/introduction/). In a nutshell it is a Base64-encoded, signed document consisting of three parts. Read more at https://auth0.com/docs/tokens/reference/jwt/jwt-structure.

Using Access Tokens in Requests

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

Authorization: Bearer <JWT token>​

For example

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

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

Caching

The same access-token can be used in multiple times (and in parallel), so we strongly recommend caching it in memory and sharing it within the same JVM. In other words, do not request a new access-token for each API request; doing that will add delay and unnecessarily strain our systems (read: if so we might be forced to disable your client).

Expiry and reauthentication

Access tokens are short lived and will expire after a certain amount of time. If the token is expired, API calls will return HTTP 401. Keep track of the remaining time using the expires_in sibling field returned by the client credentials call.

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