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` Optional	URI String	URI of your application endpoint called by the Authentication Service with a code. The parameter is optional if your client identifier is configured with a single redirect URI. 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}

Name	Data type	Description	Example
`errors` Required	string	Error code to be handled by your service.	unsupported_response_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` Optional	URI String	URI of your application endpoint called by the Authentication Service with a code. The parameter is optional if your client identifier is configured with a single redirect URI. 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

Error	Http Status Code	Response
Invalid / Expired Token	`401`
Invalid Grant Type	`400`	`{"error": "unsupported_grant_type"}`
Missing Required Param	`400`	`{"error": "invalid_request", "error_description": "Required field [XXX] was not present in the request"}`
Invalid Client (no/bad auth method used)	`400`	`{"error": "invalid_client`"}
Invalid Client (doesn’t exist / bad credentials)	`401`	`{"error": "invalid_client"}`
Token Generation Refused (throttle)	`429`	`{"error": "too_many_tokens"}`
Invalid Token (Refresh)	`400`	`{"error": "invalid_grant", "error_description": "invalid_token"}`
No Access (No Roles Setup)	`400`	`{"error": "invalid_grant", "error_description": "access_denied"}`
Generic Error	`400`	`{"error": "invalid_grant"}`

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