Searching...

Matching results

    Web Services API

    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 your region's data center (for example, na.airvantage.net and eu.airvantage.net for USA and Europe respectively). (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.

    There are different ways to request an access token:

    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.

    It is strongly recommended, specially for public applications such as native apps, to use Proof Key for Code Exchange (abbreviated PKCE). It is an extension to the authorization code flow to prevent CSRF and authorization code injection attacks. The technique involves the client first creating a secret on each authorization request, and then using that secret again when exchanging the authorization code for an access token. This way if the code is intercepted, it will not be useful since the token request relies on the initial secret.

    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 RECOMMENDED. Indicates the URL to return the user to after authorization is complete. This field is REQUIRED when no URI was set during the client registration process or the client application is considered as public. When several redirect URIs have been registered this field will select the one you require to be redirected to. The URI MUST be an absolute URI and MUST NOT include fragment components. optional   string
    state RECOMMENDED. This value is used by the client to maintain state between the request and callback. optional   string
    code_challenge RECOMMENDED. When applications begin the authorization request, the client first creates what is known as a “code verifier“. This is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.
    Once the app has generated the code verifier, it uses that to derive the code challenge. For devices that can perform a SHA256 hash, the code challenge is a Base64-URL-encoded string of the SHA256 hash of the code verifier. Clients that do not have the ability to perform a SHA256 hash are permitted to use the plain code verifier string as the challenge, although that provides less security benefits so should really only be used if absolutely necessary.    		 optional   string
    code_challenge_method Either plain or S256, depending on whether the challenge is the plain verifier string or the SHA256 hash of the string. optional plain 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 fragment components. required   string
    code_verifier Required when a code verifier was generated before the authorization request. 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_secret
    The 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

    Create a Code verifier for PKCE extension

    If you are not familiar with PKCE you can learn more about it here

    The code verifier has to be a strong cryptographically random encoded as a Base64 URL string [characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde)], between 43 and 128 characters long. A 32 byte string gives you a 43 characters size string.

    It is strongly recommended to use the S256 code challenge method. So you will need to hash the code verifier using the SHA256 algorithm.

    The resulting hash has to be encoded as a Base64 URL string.

    Expire a Token

    /api/oauth/expire

    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.
    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
    200 OK

    No specific return is sent. Only a 200 http status response is sent back.
    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

    While invoking services, several validations are made before returning results.
    When errors are raised, an error code is returned with parameters. 

    {
    "error" : "unknown.label", // error code
    "errorParameters" : "Crashed" // details relative to error code
}

    Each resource service has its own error codes. However there are some generic errors.

    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

    If you want to use "," character in list, you must escape it with "\".
    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

    If you want to use "," or ":" characters in map, you must escape them with "\".
    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

    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

    • offset: Set the first row to retrieve. If not set, rows will be retrieved from the beginning.
    • size: Set the maximum number of items to retrieve (between 0 and 500). If not set, a maximum of 100 items will be returned.

    Example:

    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.

    The returned list will have

    • items : an array with at must size items that matched the criteria (with the value of size from the query)
    • size : the number of elements returned (should be the same as items.length)
    • count : the total number of elements that matched the criteria in the database (potentially much more than the value of size from the query)

    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 

    {

items : [ { uid : "..." } , { uid : "..." } , { uid : "..." } ],
size : 3,
count : 50
}

    Filtering

    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.

    Sorting

    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.
    Do not forget that results are paginated. 

    https://na.airvantage.net/api/v1/applications?asc=creation

    You can also sort by several fields.

    https://na.airvantage.net/api/v1/applications?asc=creation,name

    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

    https://na.airvantage.net/api/v1/applications?asc=creation&desc=name

    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.

    https://na.airvantage.net/api/v1/applications?asc=name,creation&desc=name

    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.

    Password rules

    Rules use to validate a password are as follows:

    • Require between 8 and 16 chars
    • Require at least 1 digit
    • Require at least 1 non-alphanumeric char
    • Require at least 1 alphabetical char
    • White space are prohibited
    • Alphabetical sequences are prohibited
    • Numerical sequences are prohibited
    • Qwerty sequences are prohibited
    • 4 repeat characters are prohibited
    TOP