Authentication

Authentication is based on the OAuth2 standard. All requests need to be authenticated with the client credentials OAuth2 flow.

tip

All of the below details will be handled by the vasystem-api Rust crate and vasystem-api-go Go package.

For these libraries, you will only need to obtain a client ID and secret, as detailed below. You will also need to select the correct scopes for your application. After that, you can continue to the Rust or Go tutorials.

Obtaining an access token

To obtain the client ID and secret, you need to create an application on the VA website. This is currently not possible for third parties, so you need to contact the VA team to get access to the API.

Scopes

The API supports the following scopes:

• airlines: Allows access to the airlines endpoint
• routes: Allows access to the routes endpoint

Find the correct URLs for the VA

Along with the client ID and secret, you will obtain the URL for the token endpoint. This is the URL you need to use to obtain an access token. To do so, use the client_credentials flow as specified in the OAuth2 specification (RFC6749). The only accepted way of specifying the client ID and secret is by using the Authorization header with the value Basic <base64 encoded client ID and secret>.

For every VA, you will need to use different OAuth2 URLs. You can find the correct URLs for the VA you want to connect to by requesting the path /.well-known/openid-configuration on the main VA domain. For example, for a main domain of staralliancevirtual.org, you would call https://staralliancevirtual.org/.well-known/openid-configuration. This will return a JSON object with the correct URLs for the VA. In almost all cases, you only need to use the token_endpoint. For some OAuth2 clients, you might also need to use the authorization_endpoint.

{
	"authorization_endpoint": "https://staralliancevirtual.org/oauth2/auth",
    // ...
	"token_endpoint": "https://login.staralliancevirtual.org/oauth2/token",
    // ...
}

tip

Instead of hard-coding the VA and corresponding token URL, we recommend allowing a domain to be specified and retrieving the /.well-known/openid-configuration document to retrieve the token URL.

Example flow

tip

We recommend using an OAuth2 library to handle the authentication for you.

For this example, we will use the following values:

Name	Value
Client ID	client-id
Client Secret	client-secret
Token URL	https://login.staralliancevirtual.org/oauth2/token
OpenID configuration	https://staralliancevirtual.org/.well-known/openid-configuration

curl -X POST \
  https://login.staralliancevirtual.org/oauth2/token \
  -u client-id:client-secret \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials'
  -d 'scope=airlines routes'

This will return an access token:

{
  "access_token": "<your access token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "airlines routes"
}

You may optionally get a refresh token.

Once you have an access token, you can use it to make requests to the API. To do so, you need to add the Authorization header with the value Bearer <your access token>.