API Overview
This section describes the API of AirVantage. To test AirVantage API, you can view the Getting Started.
The main entity of AirVantage is a System. It represents a real system: the
physical objects, the associated data and its possible interactions.
You can start to play with the API of this entity to understand how the API works.
All API access is over HTTPS and accessed from the na.airvantage.net or eu.airvantage.net URL (depending on the datacenter you use). All data is sent and received as JSON.
HTTP Verbs
Where possible, API strives to use appropriate HTTP verbs for each action.
- GET
- Used for retrieving resources.
- POST
- Used for creating resources, or performing custom actions.
- PUT
- Used for updating resources or collections.
- DELETE
- Used for deleting resources.
Authentication
AirVantage uses OAuth 2.0 to provide authorized access to its API. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a user by orchestrating an approval interaction between the user and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.
The post Oauth2 Simplified explains very well the main concepts of this framework.
When a user grants access to an API Client, an Access Token
is issued to access user's data using AirVantage APIs. This token has a limited lifetime of 24 hours.
To request access, an API Client MUST be registered in AirVantage.
Request an Access Token using the Authorization Code Flow
In this flow, the client application needs to obtain an authorization code before requesting and access token.
Instead of requesting authorization using the end-user credentials, the client redirects the user to AirVantage, which in turn directs the user back to the client with the authorization code.
Before directing the user back to the client with the authorization code, AirVantage authenticates the user and obtains authorization.
1. Request an authorization code
/api/oauth/authorize
Request
GET https://na.airvantage.net/api/oauth/authorize?client_id=085d82466f824079a829f301b8a1f492&response_type=code&redirect_uri=http://www.example.org
Response
AirVantage authenticates the user and ask for authorization.
When the client application obtains authorization from the user, it is redirected to the provided redirect URI with the authorization code.
http://www.example.org?code=1JV6zV
Name | Description | Use | Default | Type |
---|---|---|---|---|
response_type | Value MUST be set to "code" | required | string | |
client_id | The client id | required | string | |
redirect_uri | Not needed when a URI was previously established during the client registration process. When specified, the URI MUST be an absolute URI and MUST NOT include a fragment component. | optional | string | |
state | RECOMMENDED. This value is used by the client to maintain state between the request and callback. | optional | string |
2. Request token
Once the authorization code in hand, it is possible to request an access token.
The client MUST use the HTTP POST
method when making access token requests. Parameters are sent in the entity-body as Form-Encoded Body Parameters. The HTTP request entity-header includes the header
Content-Type : application/x-www-form-urlencoded
Also, the client MUST send its API client credentials when making requests to the token endpoint.
/api/oauth/token
Request
POST https://na.airvantage.net/api/oauth/token Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=1JV6zV
Response
If your application is successfully authenticated, the authorization server will return the access token:
{ "access_token": "fe47d528-7414-4962-a7e6-ee6b82491f7a", "refresh_token": "9b465388-c9e2-45d3-98d0-1a44a503ec40", "token_type": "Bearer", "expires_in": 43199, }
In addition to the access token, the response contains the number of seconds before the token expires and a refresh token, which can be used to obtain new access tokens using the same authorization grant.
Name | Description | Use | Default | Type |
---|---|---|---|---|
grant_type | Value MUST be set to "authorization_code" | required | string | |
code | The authorization code requested before | required | string | |
redirect_uri | If the "redirect_uri" parameter was included in the authorization request, this field is required and their values MUST be identical. The URI MUST be an absolute URI and MUST NOT include a fragment component. | required | string |
Request an Access Token using the Implicit Flow
The implicit flow is a simplified authorization code flow. It is optimized for clients implemented in a browser using a scripting language. Instead of issuing an authorization code, the access token is sent directly to the redirect URI as a fragment of the request.
Before directing the user back to the client with the access token, AirVantage authenticates the user and obtains authorization.
As this flow reduces the number of round trips to obtain an access token, only one request is needed.
/api/oauth/authorize
Request
GET https://na.airvantage.net/api/oauth/authorize?client_id=085d82466f824079a829f301b8a1f492&response_type=token&redirect_uri=http://www.exemple.org
Response
AirVantage authenticates the user and ask for authorization.
When the client application obtains authorization from the user, it is redirected to the provided callback URI with the access token in the URI fragment.
http://www.exemple.org#access_token=1185af4a-2666-4b50-8c6e-4ee866eeaf7f&token_type=Bearer&expires_in=3600
Name | Description | Use | Default | Type |
---|---|---|---|---|
response_type | Value MUST be set to "token" | required | string | |
client_id | The client id | required | string | |
redirect_uri | Not needed when a URI was previously established during the client registration process. When specified, the URI MUST be an absolute URI and MUST NOT include a fragment component. | optional | string | |
state | RECOMMENDED. This value is used by the client to maintain state between the request and callback. | optional | string |
Request an Access Token using the Resource Owner Flow
In this flow the end-user credentials (i.e. username and password) are used directly as an authorization grant to obtain an access token.
The client MUST use the HTTP POST
method when making access token requests. Parameters are sent in the entity-body as Form-Encoded Body Parameters. The HTTP request entity-header includes the header
Content-Type : application/x-www-form-urlencoded
Also, the client MUST send its API client credentials when making requests to the token endpoint.
Request
POST https://na.airvantage.net/api/oauth/token Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 Content-Type: application/x-www-form-urlencoded grant_type=password&username=myLogin@anymail.com&password=654dzzMk
Response
An access token is returned by the authorization server when your application is successfully authenticated:
{ "access_token": "fe47d528-7414-4962-a7e6-ee6b82491f7a", "token_type": "Bearer" "refresh_token": "9b465388-c9e2-45d3-98d0-1a44a503ec40", "expires_in": 43199, }
In addition to the access token, the response contains the number of seconds before the token expires and a refresh token, which can be used to obtain new access tokens using the same authorization grant.
Bad credentials from the end-user to a bad request - Invalid Grant. Bad credentials from an API client lead to bad request - Invalid Client.
Name | Description | Use | Default | Type |
---|---|---|---|---|
grant_type | Value MUST be set to "password" | required | string | |
username | The user's email, encoded as UTF-8 | required | string | |
password | The password, encoded as UTF-8 | required | string | |
factor | A 6 character code sent to you via SMS when 2-factor authentication has been activated for your company. Not needed in other cases. | string |
Refresh Access Tokens
When a client acquires an access token, the client also receives a refresh token. Refresh tokens are typically long-lasting credentials used to obtain new access tokens when they become invalid or expired.
The client has to make a refresh request to the token endpoint by adding the right parameters.
Refresh tokens are valid for 30 days. When the client does a refresh request, the actual refresh token is consumed and a new refresh token will be issued for the new access token.
The client MUST use the HTTP POST
method when making access token requests. Parameters are sent in the entity-body as Form-Encoded Body Parameters. The HTTP request entity-header includes the header
Content-Type : application/x-www-form-urlencoded
Also, the client MUST send its API client credentials when making requests to the token endpoint.
/api/oauth/token
Request
POST https://na.airvantage.net/api/oauth/token Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=9b465388-c9e2-45d3-98d0-1a44a503ec40
Response
If your application is successfully authenticated, the authorization server will return a new access token along with a new refresh token:
{ "access_token": "fe47d528-7414-4962-a7e6-ee6b82491f7a", "refresh_token": "4dae4ee7-3fce-47de-825b-bb675b60c374", "token_type": "Bearer", "expires_in": 43199, }
In addition to the access token, the response contains the number of seconds before the token expires and a refresh token, which can be used to obtain new access tokens using the same authorization grant.
The refresh token is regenerated on every refresh request.
An invalid refresh token will finish with a 400 Bad Request when invalid grant.
Name | Description | Use | Default | Type |
---|---|---|---|---|
grant_type | Value MUST be set to "refresh_token" | required | string | |
refresh_token | The refresh token sent by the authorization server when it authenticates the client and validates the authorization grant | required | string |
Access Token Usage
The client accesses protected resources in AirVantage by presenting the access token
The method in which the client utilizes the access token to authenticate with the AirVantage involves using the HTTP "Authorization" request header field RFC2617
For example:
GET https://na.airvantage.net/api/v1/applications Authorization: Bearer fe47d528-7414-4962-a7e6-ee6b82491f7
Another possibility is to send the access token in the HTTP request URI, the client adds the access token to the request URI query component. However, its use is not recommended, due to its security deficiencies.
For example:
https://na.airvantage.net/api/v1/applications?access_token=fe47d528-7414-4962-a7e6-ee6b82491f7&name=myApplication
Because of the security weaknesses associated with the URI method, including the high likelihood that the URL containing the access token will be logged, it SHOULD NOT be used unless it is impossible to transport the access token in the "Authorization" request header field.
Authenticating an API client
API Clients MUST authenticate with AirVantage when making requests to the token endpoint. Client credentials (client_id/client_secret) are issued when the API Client is registered in AirVantage.
It is highly recommended to use the HTTP Basic authentication scheme [RFC2617] to authenticate API clients with AirVantage.
For example. The user agent wishes to send the client_id "my_client" and the client_secret "the_secret". First, it will create the credentials by separating the client_id and client_secret by a single colon (:)
my_client:the_secretThe resulting string has to be Base64 encoded (mostly all programming languages have libraries to do that. Or use an online encoder for testing).
bXlfY2xpZW50OnRoZV9zZWNyZXQ=The basic credentials are built like this
Basic bXlfY2xpZW50OnRoZV9zZWNyZXQ=Finally, the basic credentials are set into the Authorization HTTP header.
POST https://na.airvantage.net/api/oauth/token Content-Type: application/x-www-form-urlencoded Authorization: Basic bXlfY2xpZW50OnRoZV9zZWNyZXQ= grant_type=authorization_code&code=1JV6zV&
Alternatively, the authorization server MAY support including the client credentials in the request-body using the following parameters:
Name | Description | Use | Default | Type |
---|---|---|---|---|
client_id | The client id | required | string | |
client_secret | The client secret key | required | string |
Including the client credentials in the request-body using the two parameters is NOT RECOMMENDED and SHOULD be limited to clients unable to directly utilize the HTTP Basic authentication scheme. The parameters can only be transmitted in the request-body and MUST NOT be included in the request URI.
POST https://na.airvantage.net/api/oauth/token Content-Type: application/x-www-form-urlencoded grant*type=authorization_code&code=1JV6zV&client_id=my_client*&client_secret=the_secret
When AirVantage authenticates a client, an access token is sent with an expiration date. After this date, the token will not be valid at all.
No specific return is sent. Only a 200 http status response is sent back.
While invoking services, several validations are made before returning results. Each resource service has its own error codes. However there are some generic errors. If you want to use "," character in list, you must escape it with "\". If you want to use "," or ":" characters in map, you must escape them with "\". All queries returning a list of resources are paginated. Default pagination does not have any offset and may contain up to 100 elements. Use the following Request Parameters to paginate your queries Example: The returned list will have Example : Assuming there are 100 applications in the DB, and 50 applications that match the criteria,
https://na.airvantage.net/api/v1/applications?size=3&criteria=whatever
would return
It is also possible to ask only specific information. Instead of getting items with an unneeded record, clients can filter the fields that
have to be returned.
Use the request parameter: fields, which is a string list. See types sections to see how to
build string lists.
https://na.airvantage.net/api/v1/applications?fields=state,name
will return applications filled up only with their unique identifier, their state and their name.
When the fields parameter is missing, only default attributes are returned. Default attributes are dependent of the returned records.
When queries are requested, results can be sorted.
Sorting results are done using the asc and desc fields. As you may guess asc stands for ascending order and desc
for descending order.
The following line will return all the applications visible to the caller. Results will be sorted from the first created to the last created. You can also sort by several fields. In previous call, result items will be sorted first by creation date, from the first created to the last, and then by name. It is possible to combine ascending and descending sortings It is important to know that ASC sortings are done first. When an attribute is sent accidentally in either asc or desc, The asc ordering will be ignored. The previous call will sort by creation ascending and by name descending. See the information frame on GET methods to know which fields can be sorted. Rules use to validate a password are as follows:Expire a Token
/api/oauth/expire
It is also possible to expire a token explicitly. When the access_token is expired by this API, the related refresh_token will be expired too.
Request
GET https://na.airvantage.net/api/oauth/expire?access_token=444a378a-19fe-4de9-b056-c662f633d73d
...
Response
A 401 is sent when the token is not valid.
Name
Description
Use
Type
access_token
The token to expire
required
string
HTTP Method
GET
Requires Authentication
Yes
Rate Limited
No
Headers
None
Permissions
None
Error codes
When errors are raised, an error code is returned with
parameters.
{
"error" : "unknown.label", // error code
"errorParameters" : "Crashed" // details relative to error code
}
Error
Has parameters
Raised when
access.forbidden
No
the user does not have enough rights
unknown.partner
No
the context is not valid for the user
Types
Name
Description
Example
uid
Unique identifier. It is a string
16345d77a03f4882a97f79fe33cd581f
string list
A comma separated string list.
string1,string2,string3
string map
A comma separated string map.
key1:value1,key2:value2,key3:value3
timestamp
number of milliseconds since January 1, 1970, 00:00:00 GMT.
1349906528204 is 10 Oct 2012 22:02:08.204 UTC
Test it here NB. Remove the last three digits in any unix timestamp convertor.
Useful Information for List
For example:
If you want to send the following list:
"strin,g1", "string2", "string3"
You need to write this:
strin\,g1,string2,string3
Useful Information for Map
For example:
If you want to make the following map:
"key1":"val:ue1", "key2":"valu,e2", "key3":"val,:ue3"
You need to write this:
key1:val\:ue1,key2:valu\,e2,key3:val\,\:ue3
Paging
https://na.airvantage.net/api/v1/applications will return a maximum of 100 applications from the first record.
https://na.airvantage.net/api/v1/applications?offset=50 will return a maximum of 100 applications beginning from the 50th record.
https://na.airvantage.net/api/v1/applications?size=50 will return a maximum of 50 applications from the first record.
https://na.airvantage.net/api/v1/applications?offset=50&size=50 will return a maximum of 50 applications beginning from the 50th record.
{
items : [ { uid : "..." } , { uid : "..." } , { uid : "..." } ],
size : 3,
count : 50
}
Filtering
Sorting
Do not forget that results are paginated.
https://na.airvantage.net/api/v1/applications?asc=creation
https://na.airvantage.net/api/v1/applications?asc=creation,name
https://na.airvantage.net/api/v1/applications?asc=creation&desc=name
https://na.airvantage.net/api/v1/applications?asc=name,creation&desc=name
Password rules