Authentication API Documentation

To use the IAGL Avios API, partners need to register and ​obtain an API key​ for our staging environment. A different key will be provided when the partner application is deployed to live.

The Avios API offers loyalty services across 3 programmes:

• British Airways Executive Club
• Aer Lingus AerClub
• Vueling Club

Member authentication is mandatory for most of the Avios endpoints and achieved through an ​Oauth2 Authorisation Code flow​:

1. When a member attempts authentication, the partner application will present a third-party login form according to their programme.
2. After the Authentication system validates the partner and lets the member enter their credentials.
3. The Authentication system validates the member and returns an auth_code to the partner application.
4. The partner sends a request to the Authentication system with the auth_code and the authorisation code grant_type.
5. The Authentication system generates and returns a token to the partner, which can be passed into subsequent requests to call other Avios endpoints.

Client credentials authentication is applicable to some Avios endpoints through an ​Oauth2 Client Credentials flow​:

1. The partner sends a request to the Authentication system with its client identifier and secret and the client credentials grant_type.
2. The Authentication system generates and returns a token to the partner, which can be passed into subsequent requests to call other Avios endpoints.

The token issued depends on the programme.

Authentication Service Registration

Each API endpoint may require one or more of these authentication types:

• No authentication; the access permission is uniquely controlled by the API key
• Member authentication
• Client authentication

Please consult the documentation of each endpoint to see what type of authentication to use.

You will be provided, for each environment (see ​BAEC Environments and Authentication Endpoints​), with:

• A numeric client identifier (identical for both Member and Client authentication)
• A password for the client identifier

These credentials are to be kept secret.

In order to use of the BAEC Member Authentication Service you will be asked to provide for each environment (see ​BAEC Environments and Authentication Endpoints​):

• One or more URI for the web service in your application to receive a callback from the BAEC Authentication Service with an authorisation code

Member and client authentication are described below.

Member Authentication

Step 1. Obtain an Authorisation Code

Your application direct the member to the member login form:

URI Parameters

Authorisation Code Endpoint

'GET https://{ENV-DOMAIN-NAME}/auth/login?client_id=aviosapipartners-{CLIENT-ID}&response_type=code&redirect_uri={URI-FOR-CALLBACK-WITH-CODE}'

Example:

GET https://ecp-prelive.baplc.com/auth/login?client_id=aviosapipartners-00000&response_type=code&redirect_uri=http://localhost:8080/auth

Response

The response is a 302 redirect to the specified URI.

https://{REDIRECT_URI}?code={CODE_FOR_TOKEN_REQUEST}

Main Error Cases

The error responses are also 302 redirect to the specified URI.

http://{REDIRECT_URI}?error={ERROR_CODE}

Most error cases are displayed to the user:

• Misspelled client id ‘aviosapipartners’ will result in an HTTP 400 error
• Bad username or password will result in a message displayed on the login page
• Unregistered redirect URI will result in a “Security Issue” page to be displayed

Step 2. Obtain a Member Token

Once you have received the user’s Authorisation Code (from Step 1. above) a request must be made for a Token using the Grant service.

Your service will then form a request to obtain a token, using the with:

• Grant type: authorization_code
• Code: supplied in the authentication server redirect request

Request Headers

Example request

'POST https://{ENV-DOMAIN-NAME}/api/grant'

Request Elements

Example request body

{
  "grant_type": "authorization_code",
  "code": "1eebd3387c26f94539e8bd288f68cbcb"
}

Example response

{
  "access_token": "17507d48f57cf8183da266141ed65b6d",
  "refresh_token": "a34879d0a9b61e9ab9e16ef1b689158d",
  "scope": "AUTHN-LEVEL-12",
  "ba_refresh_expires_in": 600,
...Show more

Step 3. Refresh a Member Token

Your service can request a new token, using the refresh_token grant of the Grant service with:

• Grant type: refresh_token
• Refresh token: supplied in the response for your initial token grant

Request Headers

Example request

' POST https://{ENV-DOMAIN-NAME}/api/grant'

Request Elements

Example request

{
  "grant_type": "refresh_token",
  "refresh_token": "ad2b204bb782e873fda70ee8d0ec96a6"
}

Example responses

{
  "access_token": "5c977c8c48fe225845919a9494d53127",
  "refresh_token": "74edddd818b301101841ade2e483cd2f",
  "scope": "AUTHN-LEVEL-12",
  "ba_refresh_expires_in": 2592000,
...Show more

Client authentication

Obtain a client token

Your service will obtain a member token using the Grant service with:

• Grant type: client_credentials

Request Headers

Example request

'POST https://ecp-prelive.baplc.com/api/grant'

Request Elements

Example response

{
  "access_token": "324d27b0dc5cdae6019c8c601ac5392b",
  "scope": "AUTHN-LEVEL-15",
  "token_type": "bearer",
  "expires_in": 3600
...Show more

Grant Service

Request Headers

Example request

'POST https://{ENV-DOMAIN-NAME}/api/grant'

Request Elements

Response Elements

Example response

{
  "access_token": "17507d48f57cf8183da266141ed65b6d",
  "refresh_token": "a34879d0a9b61e9ab9e16ef1b689158d",
  "scope": "AUTHN-LEVEL-12",
  "ba_refresh_expires_in": 36000,
...Show more

A success will return the HTTP code 200 with the following JSON payload.

Main Error Cases

BAEC Environments and Authentication Endpoints

The BAEC Authentication Service is available in 2 environments. Their domain name and endpoints are as following: