CloudAhoy publishes API endpoints secured using OAuth 2.0 and currently supports the OAuth 2.0 Authorization Code Flow. To request access to the APIs, contact team@cloudahoy.com
Requesting Access to a User’s CloudAhoy Data
To access a user’s CloudAhoy data, the user must grant access to a specific application. Applications need to redirect the user to the following:
https://www.cloudahoy.com/integration/v1/auth
The following parameters need to be provided in the query string:
| Parameter | Value | Notes |
|---|---|---|
response_type |
code |
code is currently the only supported value |
client_id |
The CloudAhoy-provided client id of your application | |
redirect_uri |
Url to which the user will be redirected after approving or declining the authorization | The URL must appear in the whitelist of URLs configured for your application |
scope |
flights:read |
Space-delimited list of valid scopes. Currently, flights:read is the only supported scope |
state |
random string | Used to prevent CSRF attacks; recommend 16 to 32 characters in length |
Authorization Request Approved
If the user approves the request, the user will be redirected to the redirect_uri provided via the query string. The following query-string arguments will be provided:
| Parameter | Value | Notes |
|---|---|---|
code |
Random string | The authorization code that may be exchanged for an OAuth token. The code will be valid for 5 minutes. |
state |
State value provided to call to /auth |
Authorization Request Declined or Failed
If the user declines the request or has a problem processing the request, the user will be redirected to the redirect_uri provided via the query string. The following query-string arguments will be provided:
| Parameter | Value | Notes |
error |
Error code |
One of:
|
error_description |
Description text | Text description or additional details about the error |
state |
State value provide to call to /auth |
See this article’s “Error” section for descriptions of the error codes.
Exchanging a Code for an Access Token
Applications must exchange the code provided via the redirect for an OAuth access token. To do so, the application must make a POST request to:
https://www.cloudahoy.com/integration/v1/token
As this request involves transferring a secret, the POST request should be made from the application’s server.
The following form or JSON parameters must be provided with the POST:
| Parameter | Value | Notes |
|---|---|---|
grant_type |
authorization_code |
authorization_code is the only supported value |
code |
The access code provided via the redirect from /auth | |
redirect_uri |
URI provided to the call to /auth | Must exactly match the URI provided to the call to /auth |
client_id |
Your client’s id | Provided to you by CloudAhoy |
client_secret |
Your client’s secret | Provided to you by CloudAhoy |
Token request successful
If the token request succeeds, CloudAhoy will return a JSON object with the following structure:
| Property | Value | Notes |
|---|---|---|
access_token |
The OAuth access token | Token has no expiration |
type |
bearer |
bearer is the only value that will be returned. |
Token request unsuccessful
If the token request fails, CloudAhoy will return a JSON object with the following structure. The response will have an HTTP status code of 400 unless otherwise noted.
| Parameter | Value | Notes |
|---|---|---|
error |
Error code |
One of:
|
error_description |
Description text | Text description or additional details about the error |
Please see this article’s “Unsuccessful Response” for descriptions of the codes.
Accessing OAuth-secured Endpoints
All requests to OAuth-secured endpoints must include an Authorization header, which provides the access token on behalf of which the request is being made:
Authorization: Bearer <user's access token>
The scope of the resource being access, e.g., the user’s flights, must match one of the scopes associated with the access token.
Last Updated: