IVAO Public APIs don't require any authentication nor access request.
This section of the IVAO DevOPS Documentation wiki describes important information on how to retrieve data from IVAO servers as a client-side application.
This section of the IVAO DevOPS Documentation wiki describes important information on how to retrieve data from IVAO servers as a client-side application.
This section of the IVAO Web Development Documentation wiki describes how you can send your data to the FPL system externally. For more information, visit the next link.
IVAO Private APIs require users to be authenticated in order to query them. Click Here to get request your own access
IVAO Private API Documentations could be found under this link.
IVAO OAuth Scopes description can be found here.
NEW: IVAO API Keys are now avaliable. Get yours at our Developers Website
Notice: IVAO API access is now open to everyone! Do not hesitate to request your own access here!
The easiest way to use our APIs, once you generated credentials on the Developers website, is to generate an API Key that you can pass as:
https://api.ivao.aero/v2/airports?apiKey=YOUR_API_KEY_GOES_HEREapiKeyYOUR_API_KEY_GOES_HEREFor both ways, accepted names are case-insensitive:
apiKeyapikeyAPIKEYx-api-keyX-API-KEYYou can find an example here
This will authenticate you as an application and you won't be able to endpoints that expect a form of user authentication (e.g.,
/v2/users/me/*)
To use OAuth2 to authenticate your application, please refer to our samples repository that documents it all and gives you samples a multiple coding languages: ivaoaero/OAuth-samples
With this method, you can either authenticated as an app (
client_credentialsflow), or on behalf of a user (through SSO) to perform some actions
If you want to access some user personal information or perform actions on their behalf, you need their consent first (due to GDPR reasons).
To do so, you need to put the user through the OAuth2 flow, with the needed scopes, at least once. Once the user has consented to grant you the requested grants, you can use one of the following authentication methods to make the request:
TL;DR, you don't need to store the user's Access Token to continue accessing the API on his behalf, just use your app's credentials and the API will be able to check if consent was granted in the past.
You want the firstName, lastName, email for user 485573.
If you make a request to https://api.ivao.aero/v2/users/485573 with your app's API Key or OAuth2, you will only receive the public data related to that user (division, country, ratings, hours, staff positions, etc...)
First, you need to put the user through SSO with the scopes profile & email, in return you'll get the user's OAuth2 Access token. But, you aren't forced to use it to make the request as the user's consent is now linked to the application that redirected the user to SSO.
Now, if you make the request https://api.ivao.aero/v2/users/485573 with any form of authentication listed above, you will be able to get the user's firstName, lastName, and email !
In addition to the standard HTTP error code, we have augmented some of our error response to detail what is happening, especially around authentication errors.
A response body is usually formatted the following way:
{
"message": "JWT verification error: jwt expired",
"error": "tokenexpired",
"statusCode": 401,
"error_uri": "https://wiki.ivao.aero/en/home/devops/api/documentation-v2#error-messages"
}
If you want to handle specific situations based on error messages, we recommend hard-coding either the HTTP Status Code or error field from the response payload. Here are the value you'll most often encounter:
not_authenticated: No OAuth2 token nor API was found in the request but is required for this endpointnot_authenticated_with_oauth2: No OAuth2 token was found in the request but is required for this endpoint
not_authenticated_as_user: No user-issued (authorization_code grant) OAuth2 token was found in the request but is required for this endpoint
not_authenticated_as_application: No app-issued (client_credentials grant) OAuth2 token was found in the request but is required for this endpoint
hq_application_required: This endpoint is restricted to HQ-managed apps
missing_permissions: The user/app is missing at least one permission to access the endpointmissing_scopes: The token is missing at least one scope to access the endpointinvalid_api_key: The provided API Key isn't registered to any applicationinactive_application: The provided token/key is linked to an inactive applicationinvalid_token: Generic error occured while validating JWT tokenincorrect_token: JWT token is malformed or isn't issued by IVAOexpired_token: The provided JWT token is expirednot_before_token: The provided token is not yet valid (should never happen with IVAO issuers)revoked_token: The provided token was revokednot_found: Classic 404 error, either the route doesn't exist or the requested resource (by id) doesn't existforbidden: Classic 403 error, you don't have access to that endpoint/resourceunauthorized: Classic 401 error, no authentication method (OAuth token or API Key) where found in the requestbad_request: The payload doesn't match the expected format or contentPlease check that your code isn't checking against any of those messages, as they have been replaced with the payload above:
This auth token has been revoked or expiredCouldn't extract token from requestNo auth token found in requestCouldn't decode auth tokenCouldn't verify if that token existCan't find the token issuerCan't find the host from the requestThis host is not allowed for this token issuerAuth token issued by a non-approved sourceFailed to find the application detailsFailed to find the consumerFailed to authenticate the consumerThe reponse you get from the API is really close to how our database is structured behind the scenes. This is why some values are IDs referencing other rows, but not always included in the body. Here is a list of most common references you might encounter while using our API.
If you encounter that isn't listed down below, please get in touch with us.