Authentication API Documentation

v1Showing BAEC specific information

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:

When a member attempts authentication, the partner application will present a third-party login form according to their programme.
After the Authentication system validates the partner and lets the member enter their credentials.
The Authentication system validates the member and returns an auth_code to the partner application.
The partner sends a request to the Authentication system with the auth_code and the authorisation code grant_type.
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:

The partner sends a request to the Authentication system with its client identifier and secret and the client credentials grant_type.
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.

Programme	Grant Authorisation	Token
British Airways Executive Club	client_id (Confidential)	Oauth2 Bearer token Or JWT
Aer Lingus AerClub	Basic Auth	JWT
Vueling Club	Basic Auth	JWT

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

Name	Data type	Description	Example
`client_id` Required	String	Client identifier unique for your application. Format: aviosapipartners-xxxxx where xxxxx is your 5-digit id	aviosapipartners-00000
`response_type` Required	String	Response type indicating the OAuth 2 flow requested. Value must be set to 'code' always. Format: code	code
`redirect_uri` Conditional	URI String	URI of your application endpoint called by the Authentication Service with a code. If your client identifier is configured with a single redirect URI then this is not required. If multiple redirect URIs are attached to the client identifier then this parameter must be populated with the redirect URI you wish to use. Format: your valid URI must have been configured during registration.	http://localhost:8080/auth

Response

The response is a 302 redirect to the specified URI.

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

Name	Data type	Description	Example
`code` Required	String	Alphanumeric code to be used by your service to request a grant. This code expires within 2 minutes. Format: alphanumeric	ad2b204bb782e873fda7 0ee8d0ec96a6

Main Error Cases

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

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

HTTP Status Code	Description
`400` INVALID_REQUEST INVALID_REQUEST	Missing programme-identifier (empty or not sent) Grant type missing Grant type blank Invalid/missing username or password (both values must be provided and valid) Invalid username format (can't contain "." or "-" at the beginning or the end) Invalid scope (scope can be read, reset_password, retrieve_account, retrieve_membership, contact_member, reverse_transaction, write retrieve_username)
`401` REQUEST_UNAUTHORIZED UNAUTHORIZED	Invalid Programme Identifier or OAUTH Token in the header or the Oauth token has expired Decrypted partner-id:partner-secret Invalid/missing/blank authorization Invalid/missing username or password (both values must be provided and valid) Invalid/void partner ID or secret (both need to be provided and valid) Customer status is inactive Account is blocked Account status is fraud Password has expired
`401` REQUEST_UNAUTHORIZED UNSUPPORTED_GRANT_TYPE	Wrong grant type

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'

Name	Data type	Description	Example
`Authorization` Required	String	The BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password ) Format: Basic {BASE64_ENCODED_CREDENTIALS}	Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
`Content-Type` Required	String	The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/x-www-form-urlencoded is accepted. Format: application/< content-type>	application/x-www-form-urlencoded

Request Elements

Example request body

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

Name	Data type	Description	Example
`grant_type` Required	String	The grant type for the token. Format: authorization_code	authorization_code
`code` Required	String	The code provided by the auth server. Format: 256-bit key, lowercase hexadecimal	1eebd3387c26f94539e8 bd288f68cbcb
`redirect_uri` Conditional	URI String	URI of your application endpoint called by the Authentication Service with a code. This specific header is dependent on whether or not you passed the redirect URI in your authorisation code request. Format: your valid URI must have been configured during registration.	http://localhost:8080/auth

Example response

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

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'

Name	Data type	Description	Example
`Authorization` Required	String	The BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password ) Format: Basic {BASE64_ENCODED_CREDENTIALS}	Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
`Content-Type` Required	String	The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/x-www-form-urlencoded is accepted. Format: application/< content-type>	application/x-www-form-urlencoded

Request Elements

Example request

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

Name	Data type	Description	Example
`grant_type` Required	String	The grant type for the token. Format: refresh_token	refresh_token
`refresh_token` Required	String	The code returned with the member token	ad2b204bb782e873fda7 0ee8d0ec96a6

Example responses

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

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'

Name	Data type	Description	Example
`Authorization` Required	String	The BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password ) Format: Basic {BASE64_ENCODED_CREDENTIALS}	Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
`Content-Type` Required	String	The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/x-www-form-urlencoded is accepted. Format: application/< content-type>	application/x-www-form-urlencoded

Request Elements

Name	Data type	Description	Example
`grant_type` Required	String	The grant type for the token. Format: client_credentials	client_credentials

Example response

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

Grant Service

Request Headers

Example request

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

Name	Data type	Description	Example
`Authorization` Required	String	The BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password ) Format: Basic {BASE64_ENCODED_CREDENTIALS}	Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
`Content-Type` Required	String	The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/x-www-form-urlencoded is accepted. Format: application/< content-type>	application/x-www-form-urlencoded

Request Elements

Name	Data type	Description	Example
`grant_type` Required	String	The grant type for the token. Format: authorization_code for member token; client_credentials for partner tokens; refresh_token for requesting a new member token	authorization_code
`code` Optional	String	The code provided by the auth server. This code is required for `authorization_code` grant types and expires within 2 minutes.	1eebd3387c26f94539e8b d288f68cbcb
`refresh_token` Optional	String	The refresh token is required for `refresh_token` grant.	324d27b0dc5cdae6019c8 c601ac5392b

Response Elements

Example response

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

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

Name	Data type	Description	Example
`access_token` Required	String	The access token. Expires as indicated in expires_in	324d27b0dc5cdae6019c8 c601ac5392b
`refresh_token` Optional	String	The refresh token. Provided in the case of a grant of types authorisation_code and refresh_token. Expires as indicated in ba_refresh_expires_in.	324d27b0dc5cdae6019c8 c601ac5392b
`scope` Required	String	Authorisation level. May have a different number at the end (representing how securely the user is considered to have authenticated) Format: AUTHN-LEVEL-10, AUTHN-LEVEL-12, AUTHN-LEVEL-15 (highest)	AUTHN-LEVEL-15
`token_type` Required	String	Token type. Indicates how the token should be used. Format: bearer	bearer
`expires_in` Required	Integer	Token lifetime in seconds.	84600
`ba_refresh_expires_in` Optional	Integer	Refresh token lifetime in seconds. Only present for grants of type authorization_code.	259200

Main Error Cases

HTTP Status Code	Description
`400` INVALID_REQUEST INVALID_REQUEST	'ProgrammeIdentifier' is missing Missing grant type Missing business-context-identifier
`400` INVALID_REQUEST UNAUTHORIZED	Request is not authorized
`400` INVALID_REQUEST INVALID_SCOPE	Request scope is not valid (possible scopes : reset_password retrieve_membership, retrieve_account contact_member reverse_transaction, write retrieve_username)
`401` REQUEST_UNAUTHORIZED UNAUTHORIZED	Request is not authorized
`405` METHOD_NOT_ALLOWED METHOD_NOT_ALLOWED	The requested method is not supported

BAEC Environments and Authentication Endpoints

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

Environment	Web service	Endpoint
Pre-live	Login page	https://ecp-prelive.baplc.com/auth/login
	Grant	https://ecp-prelive.baplc.com/api/grant
Live	Login page	https://www.britishairways.com/auth/login
	Grant	https://www.britishairways.com/api/grant