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
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 client_secret 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.
Updated 10 months ago