Authentication

Introduction

API authentication is based on the OAuth 2.0 standard which is supported by virtually all development environments. There are two scenarios for authentication via OAuth 2.0 which are supported:

  1. The user account is accessed directly using the user’s credentials. This is called “client credentials”.
  2. The user account is accessed indirectly by a third party application to which the user grants permission to access the user account on his/her behalf. This is called “authorization code”.

Client Credentials authorization

A simple one-way authentication is used which makes it easy for developers that are not intimately familiar with OAuth 2.0 and its intrinsics.

The authentication method (called the “grant type”) is “client credentials”. In this model, you provide credentials (client ID and secret, i.e. user and password) in exchange for an access token which is valid for some time (one hour presently). On each API request, you pass the access token as part of your HTTP header. Once the access token expires, you have to request a new one by passing your credentials.

In order to use OAuth 2.0, your account with autorouter has to be configured to allow for API access. Please request this permission via the support ticket function before starting to work with the API.

Requesting an access token

autorouter identifies you by your email address and a password that you can choose yourself (“credentials). The same credentials are used for OAuth 2.0. To request a token, you have to perform a HTTP POST to

https://api.autorouter.aero/v1.0/oauth2/token

With the following parameters passed as POST variables:

  • grant_type
    Must be set to “client_credentials”
  • client_id
    Your user ID, i.e. the email address your account is associated with.
  • client_secret
    Your password.

Simulating this request on the command line with cURL would look like this:

curl -d "grant_type=client_credentials&client_id=user@foo.com&client_secret=wonttell" --verbose https://api.autorouter.aero/v1.0/oauth2/token

The response will be a HTTP status code (200 for success) and a JSON structure with the access token information:

{
   "access_token": "f3428b087d9a353099beec85cdbe10026edf5932",
   "expires_in": 3600,
   "token_type": "Bearer",
   "scope": null
}

Note the token string and the expiration time in seconds. After this time, you will receive an error trying to use the token and have to request a new one. You do not have to remember the time but instead handle the expiration error and automatically request a new token. The token type is “Bearer” which tells you how you have to pass it to the API requests (more to follow).

In case of an error a structure like this would be returned:

{
   "error": "invalid_client",
   "error_description": "The client credentials are invalid"
}

Authorization Code

The drawback of the “client credentials” method is that you can only access one specific user account and you have to be in possession of the user’s login details. However, as a third party, you should not get to know the user’s logon and you will probably want to offer your application to many autorouter users which is what the “authorization code” method enables you to do.

In this scenario, there are three parties involved: 1) autorouter, 2) the user having an account with autorouter and 3) a third party application to which the user delegates access to his/her autorouter account. For security reasons, each third party application needs to be registered with autorouter and receive a client_id, a password and a callback URI. To register your application, please create a support ticket on autorouter.

In your OAuth2 workflow, to gain access to a user’s autorouter account, you redirect your user to

https://www.autorouter.aero/authorize

and provide the following GET parameters:

  • client_id
    Your OAuth2 client ID with autorouter, this is what you receive after registering yourself as an approved 3rd party application.
  • redirect_uri
    The URL to which autorouter redirects the user after the authorization was granted. It must be identical to the URI provided during registration as an approved 3rd party application.
  • response_type
    Has to be set to “code”.
  • state
    This should be set to a one-time non-guessable identifier which will be passed through by our API to your application and helps to ensure that the request response actually stems from your request.

If the request is successful, the autorouter server redirects the user to the address provided under “redirect_uri” passing the following GET parameters:

  • code
    This is a unique code for the authorization. It is valid for 30 seconds and may be exchanged for a token in the next step.
  • state
    The state parameter passed to the authorization request. You should compare it to the value you passed in to validate the response.

Exchanging code for access token

Similar to the client credentials method, you have to request a token, this time in exchange for the previously obtained code instead of user credentials. You have to perform a HTTP POST to

https://api.autorouter.aero/v1.0/oauth2/token

With the following parameters passed as POST variables:

  • grant_type
    Must be set to “authorization_code”
  • client_id
    The client ID of your application as obtained during the registration as approved application.
  • client_secret
    Your password as obtained during the registration as approved application.
  • code
    The code previously obtained as result of the authorization process.
  • redirect_uri
    The URL to which autorouter redirects the user after the authorization was granted. It must be identical to the URI provided during registration as an approved 3rd party application.

As a result you obtain an token just like when using client credentials but this time with a longer expiration time, currently one year.

Performing API calls

Once you have an access token using either method, you can perform API calls by passing the token with each HTTP request. As it is a bearer token, it has to be passed inside the HTTP header in the form

Authorization: Bearer f3428b087d9a353099beec85cdbe10026edf5932

Using cURL, an API request would look as follows:

curl -H "Authorization: Bearer f3428b087d9a353099beec85cdbe10026edf5932" --verbose https://api.autorouter.aero/v1.0/aircraft/templates

Should the request fail due to authorization, you will receive the appropriate HTTP status code. An invalid token is identified as code 403 (forbidden). In this case you should request a new token.

JSON Web Token (JWT) Authentication

As a more modern alternative to OAuth 2.0 client credentials authentication, autorouter also supports JSON Web Token (JWT) authentication. JWT is very similar but instead of a database driven approach where the server generates a token and stores it in a database, performing lookups for each API access, a cryptographic approach is used. The token is a JSON structure with validity information and some additional payload, base64 encoded into a string and then signed with a private key by the server. It is passed in API calls with a bearer header just like OAuth 2.0 and the server only has to validate the digital signature and then can trust the information in the token directly without performing any further validation.

The advantage is that JWT scales better (no database access) and is more suitable for federated server systems as its content can be directly used by just verifying the signature. The advantage for clients is that modern frameworks come with support for JWT and developers are familiar with it. Also, the token can contain additional payload for the application (such as user account details, privileges, etc.).

Presently the JWT API is not documented so please get in touch if you believe this suits your application needs better.