Getting Started With The API
# Using OAuth 2.0
OAuth 2.0 is a protocol that lets your app request authorization to fetch private details in a user's Flight Circle account without getting their password.
You'll need to register your app with our support team before getting started. A registered app is assigned a unique Client ID and Client Secret which will be used in the OAuth flow. The Client Secret should not be shared.
You also would want to give us a redirect_uri so your end users can be secure their data won't be leaked by an attacker.
# The OAuth Flow
The Flight Circle API uses OAuth 2.0's authorization code grant flow (opens new window) to issue access tokens on behalf of users.
The OAuth flow is your key to unlocking access tokens. There's no path to programatically create (or retrieve) app access tokens without a user's input.
# Token types
The Flight Circle API uses access_token and refresh_token tokens, the purpose of the access_token is to grant access to the API and the purpose of the refresh_token is to retrieve a new access_token without having the user login and grant permission again.
Access tokens carry the necessary information to access a resource directly. In other words, when a client passes an access token to a server managing a resource, that server can use the information contained in the token to decide whether the client is authorized or not. Access tokens are short-lived and expires after 1 hour.
Refresh tokens carry the information necessary to get a new access token. In other words, whenever an access token is required to access a specific resource, a client may use a refresh token to get a new access token issued by the authentication server. Common use cases include getting new access tokens after old ones have expired, or getting access to a new resource for the first time. Refresh tokens will also expire within 180 days but its expiration will be reseted everytime you use it to get a new
access_token. Refresh tokens are usually subject to strict storage requirements to ensure they are not leaked. They can also be blacklisted by the authorization server.
# Step 1 - Sending users to authorize and/or install
Your web or mobile app should redirect users to the following URL:
https://www.flightcircle.com/v1/api/pub/authorize
The following values should be passed as GET parameters:
client_id- issued when you created your app (required)state- unique string to be passed back upon completion (optional)
Notice you should never send client_secret on this request.
# Redirect URIs
In the OAuth2.0 protocol, you'd usually set the redirect_uri parameter in this request, but for further enhance the users security, it must be registered with us beforehand.
Until registering your desired redirect_uri value, its default value is http://localhost/example/server.php and it's not required on the request to /authorize.
You must thus send us your desired redirect_uri to our support team. You can ask for a change at any time. This way you can be sure that even if your end user is on a compromised device it will never be redirected into a malicious website.
# State
The state parameter should be used to avoid forgery attacks by passing in a value that's unique to the user you're authenticating and checking it when auth completes.
In another words, you need to check if the state you specified in the request to /authorize matches the state we send back to you on your redirect_uri endpoint.
Don't go on with the authentication process if the state didn't match. That will prevent a malicious third party to try connecting to your app.
Also, you the state allows you to easily identify which user is being connected to your app.
# Step 2 - Users are redirected to your server with a verification code
If the user authorizes your app, Flight Circle will redirect back to your specified redirect_uri with a temporary code in a code GET parameter, as well as a state parameter if you provided one in the previous step. If the states don't match, the request may have been created by a third party and you should abort the process.
Authorization codes may only be exchanged once and expire 30 seconds after issuance.
# Step 3 - Exchanging a verification code for an access token
If all is well, exchange the authorization code for an access token using the oauth.access API method (method documentation).
https://www.flightcircle.com/v1/api/pub/token
client_id- issued when you created your app (required)client_secret- issued when you created your app (required)code- a temporary authorization code (got from previous step)refresh_token- token issued on this same endpoint
You shall not pass both code and refresh_token. One of the two are required.
If you provide a valid code, you'll receive a JSON response containing an access_token and a refresh_token, among other details:
{
"access_token": "0253071b6d1cce0d119cc968f6b14ceeecc3bj75",
"refresh_token": "126f4555b483b5e8fae721b773e02fde941a785u",
}
2
3
4
If you provide a valid refresh_token, you'll receive a JSON response containing an access_token, among other details:
{
"access_token": "0253071b6d1cce0d119cc968f6b14ceeecc3bj75",
}
2
3
Access tokens for all apps are also known as bearer tokens.
You can then use this token to call API methods on behalf of the user.
# Storing tokens and credentials
Store your application's credentials and user tokens with care.
# Using access tokens
The tokens awarded to your app can be used in requests to the Web API.
The best way to communicate your access tokens, also known as bearer tokens, is by presenting them in a request's Authorization HTTP header:
GET /user/describe
Authorization: Bearer 0253071b6d1cce0d119cc968f6b14ceeecc3bj75
2
This approach is required when using application/json with a write method.
Alternatively, you may send the token as a querystring or POST body attribute of the application/x-www-form-urlencoded variety:
In a query string:
GET /user/describe?access_token=0253071b6d1cce0d119cc968f6b14ceeecc3bj75
Or a POST body:
POST /user/describe
Content-type: application/x-www-form-urlencoded
access_token=0253071b6d1cce0d119cc968f6b14ceeecc3bj75
2
3
# Token Request Flow
The first token request uses the authorization_code grant, once the token is retrieved it is stored on the client side and the refresh token grant is used from there. We suggest storing the token in a database or wherever your store your user information at.
# Example Code
In this example we built an application that shows you how to authentication on API and send a request to endpoint /user/describe.
You can also download the example code here.
For making it work, follow these steps:
Be sure you have a web server running on your machine like Apache (configuring a web server is out of the scope for this documentation)
Download the example code and extract its contents (client.php, server.php, describe_user.php) on a folder named "example" on the root of your web server folder
Be sure client.php is accessible at http://localhost/example/client.php
Modify file client.php updating $client_id with your CLIENT_ID
Modify file server.php updating both $client_id and $client_secret with corresponding keys
Access http://localhost/example/client.php
You'll get redirect to login page (or authorization page if already logged in). Log in and authorize.
You'll be redirected to http://localhost/example/server.php, which will automatically exchange your authorization code for a token and exhibit it
Click on link "Describe user to test token" and you will be redirected to the describe_user.php which will show your own user data.
If any of these steps fail, please let us know in details.
After you are done with the example and are proceeding to build your own application, let us know what is the redirect_uri you intend your integration to use.
# Notice
Please note the FlightCircle API is subject to change without notice.
# API Date Formats
All dates are returned in ISO-8601 format using the UTC format, you can find the user timezone when making a API call to /user/describe endpoint.