Authentication API Documentation

v1Showing BAEC specific information

To use the 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.

ProgrammeGrant AuthorisationToken
British Airways Executive Clubclient_id (Confidential)Oauth2 Bearer token Or JWT
Aer Lingus AerClubBasic AuthJWT
Vueling ClubBasic AuthJWT

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
NameData typeDescriptionExample
client_id
Required
StringClient identifier unique for your application.
Format: aviosapipartners-xxxxx where ​xxxxx​ is your 5-digit id
aviosapipartners-00000
response_type
Required
StringResponse type indicating the OAuth 2 flow requested. Value must be set to 'code' always.
Format: code
code
redirect_uri
Optional
URI StringURI 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}
NameData typeDescriptionExample
code
Required
StringAlphanumeric 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}
NameData typeDescriptionExample
errors
Required
stringError 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'
NameData typeDescriptionExample
Authorization
Required
StringThe BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password )
Format: Basic {BASE64_ENCODED_CREDENTIALS}
Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
Content-Type
Required
StringThe 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"
}
NameData typeDescriptionExample
grant_type
Required
StringThe grant type for the token.
Format: authorization_code
authorization_code
code
Required
StringThe code provided by the auth server.
Format: 256-bit key, lowercase hexadecimal
1eebd3387c26f94539e8 bd288f68cbcb

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'
NameData typeDescriptionExample
Authorization
Required
StringThe BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password )
Format: Basic {BASE64_ENCODED_CREDENTIALS}
Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
Content-Type
Required
StringThe 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": "authorization_code",
  "code": "1eebd3387c26f94539e8bd288f68cbcb"
}
NameData typeDescriptionExample
grant_type
Required
StringThe grant type for the token.
Format: authorization_code for member token; client_credentials for partner tokens
authorization_code
refresh_token
Required
StringThe code returned with the member tokenad2b204bb782e873fda7 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'
NameData typeDescriptionExample
Authorization
Required
StringThe BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password )
Format: Basic {BASE64_ENCODED_CREDENTIALS}
Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
Content-Type
Required
StringThe 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

NameData typeDescriptionExample
grant_type
Required
StringThe 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'
NameData typeDescriptionExample
Authorization
Required
StringThe BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password )
Format: Basic {BASE64_ENCODED_CREDENTIALS}
Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
Content-Type
Required
StringThe 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

NameData typeDescriptionExample
grant_type
Required
StringThe 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
StringThe 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
StringThe 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.

NameData typeDescriptionExample
access_token
Required
StringThe access token. Expires as indicated in expires_in324d27b0dc5cdae6019c8 c601ac5392b
refresh_token
Optional
StringThe 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
StringAuthorisation 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
StringToken type. Indicates how the token should be used.
Format: bearer
bearer
expires_in
Required
IntegerToken lifetime in seconds.84600
ba_refresh_expires_in
Optional
IntegerRefresh token lifetime in seconds. Only present for grants of type authorization_code.259200

Main Error Cases

ErrorHttp Status CodeResponse
Invalid / Expired Token401
Invalid Grant Type400
{"error": "unsupported_grant_type"}
Missing Required Param400
{"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 Error400
{"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: