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:
- 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}
HTTP Status Code | Description |
---|---|
400 INVALID_REQUEST INVALID_REQUEST | Missing programme-identifier (empty or not sent)Grant type missingGrant type blankInvalid/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 expiredDecrypted partner-id:partner-secretInvalid/missing/blank authorizationInvalid/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 inactiveAccount is blockedAccount status is fraudPassword 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 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
HTTP Status Code | Description |
---|---|
400 INVALID_REQUEST INVALID_REQUEST | 'ProgrammeIdentifier' is missingMissing grant typeMissing 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 |