OAuth 2.0 Bearer Tokens

Before you begin

Familiarise yourself with OAuth V2.0

Firstly, make sure you've got your credentials to hand. APIs that implement OAuth require version 2.0 as defined in RFC649.

We use JWT Bearer Tokens for authentication and authorization.

Once you present a valid set of API credentials to us, we'll issue a token. For each request you subsequently make to our API, you'll present your token along with the request, instead of your actual (sensitive) credentials.

There are currently two kinds of tokens that may be issued:

  • Client
  • User

Client tokens are used by client applications to call certain APIs and to obtain user tokens (via the authorize endpoint) to act on behalf of a user.

User tokens can be used by a client to call APIs that require a user context.

All token responses will include a refresh token which is used to renew the access token when it expires (after 15 minutes by default).

Obtain a Bearer token

You'll need to send us a standard HTTP request (over SSL) in order to exchange your credentials (or your users' credentials) for a token.

oauth/v2/token

This API is used to obtain either a client token, a user token or to refresh an existing token. The type of token you wish to receive is determined by the grant_type parameter you specify.

Let's take a look at an example HTTP request to obtain a client token (the parameters are explained below):

POST /oauth/v2/token HTTP/1.1
Host: auth.altitudeangel.com
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
Content-Length: 0
client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]&grant_type=client_credentials&scope=[LIST OF REQUESTED SCOPES]

The value for the grant_type parameter can be one of:

Value

Description

Extra Fields

client_credentials

Obtain a client token from a Client ID and Client Secret

client_id
client_secret
scope

authorization_code

Obtain a user token from an authorization code

client_id
code
redirect_uri

refresh_token

Use a refresh token to obtain a new access (bearer) token

client_id
client_secret
refresh_token

❗️

Don't forget that tokens expire!

Altitude Angel tokens expire every 15 minutes. Your application will need to handle the Refresh Token flow as specified in RFC6749. Most 3rd party libraries for working with OAuth2 flows will implement this for you, but it is worth calling-out that you may need to check for a subsequent HTTP 401 error and then present your Refresh Token again.

❗️

Replace demo values and HTML-encode the Client Secret!

Be sure to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET (make sure that you HTML-encode the value of Client Secret) with the values given to you.

This is a common cause of support requests to our helpdesk.

Scopes

When making your request to this endpoint, you must also specify which scope(s) you wish to request. You can think of a scope broadly, as permission to perform a particular operation. When you created your Client ID in our Developer Portal, you were asked which scopes you would require. It is not possible to request scopes that you have not explicitly declared in the Developer Portal first, however you can change scopes within the portal at any time.

Scope

Description

access_archive

Retrieve items from the user's archive information.

talk_tower

Call ops/tower APIs.

manage_users

Allows for the management and provisioning of users for organizations.

query_mapdata

Query the mapdata endpoint for ground POI information to display on a map.

query_mapairdata

Query the mapdata endpoint for air based information to display on a map. E.g. Airspace classification, no fly zones etc.

manage_flightreports

Call the flight reports API.

Note that the value of the scope parameter should be a space delimited string, such as: "query_mapdata talk_tower". This value should also be URL Encoded.

Submit the request, and you should receive a bearer token as a JSON object:

{  
  "access_token":"[ ...]",
  "token_type":"bearer",
  "expires_in":1199,
  "refresh_token":"[ ... ] "
}

Congratulations! You've now received a bearer token which you present along with every API call you now make.

oauth/v2/authorize

In order to obtain a user token the user must be asked to login using their Altitude Angel credentials and give permission for your application to act on their behalf. This will result in an authorization code being generated that can be exchanged for a user toke using the /token endpoint, above.

To obtain an authorization code, open a web browser and redirect the user to the authorize endpoint. The query string must contain the following parameters for your authorize request:

Query String Parameter

Description

response_type

Must be code

client_id

The Client ID of the requesting client application. This was given to you when you provisioned your application in our Developer Portal.

redirect_uri

The URI that the authorization process should redirect to after it completes, for example, https://www.yourcompany.com/auth.

scope

A space-separated (URL-encoded) list of required scopes.

state

(optional, recommended) State used to validate the redirect callback from the Altitude Angel authorization server back to the client application.

The redirect URI must match the URI you provided to us within the application definition in the Developer Portal.

🚧

A note about scopes

Your Client ID will have been granted access to certain scopes that govern which API calls you can make against Altitude Angel. If you need access to different scopes, please let us know. Scopes to which you are not currently entitled to use will result in an HTTP 401 error.