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 IAGL 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 Authorization 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.

This authentication applies to Aer Lingus AerClub and Vueling Club.

Usage of the Authentication API follows successful calls to both the Join Programme and Register Account endpoints. The Authentication API must be called prior to, Retrieve Membership, Update Membership, Retrieve Transaction, Debit Currency or Reverse Transaction (and to execute Debit Currency a pricing request must have been performed).

The following steps are performed by the Authentication service:

• Authenticate partner/member.
• Generate an access token.

Important Technical Notes

• The endpoint returns the response attributes in uppercase and lowercase ASCII characters as appropriate.

Pre-conditions

• In order to authenticate, the partner must have successfully registered with a supported loyalty programme.
• The partner must have then obtained from Avios the following values: a business-context-identifier, a programme-identifier, a partner secret and a client identifier.
• An account must exist within the Avios loyalty platform for the member.
• The partner must have successfully obtained auth_code.

Post-conditions

Success outcome: An access token is returned in the API response message.

Error outcome: Service error is returned.

Auth code for Partner Login Page

Partner Login Page Endpoint:

'POST https://partnerservices.avios.com/secure/code?response_type={response_type}&client_id={client_id}&scope={scope}&state={state}&brandName={brandName}&programme-identifier={programme-identifier}&business-context-identifier={business-context-identifier}'

Example:

https://partnerservices.avios.com/secure/code?response_type=code&client_id=TESTA00001&scope=READ&state=Sogo2&brandName=TESTA&programme-identifier=ATRP&business-context-identifier=BCI

Authentication Grant Type: Authorization_code

Authorization_code Grant Type Endpoint:

https://partnerservices.avios.com/secure/key?grant_type={grant_type}&code={code}&client_id={client_id}

Example:

https://partnerservices.avios.com/secure/key?grant_type=authorization_code&code=oIjPSa&client_id=TESTA00001

Authentication Headers for grant Type: Authorization_code

Request Elements

There is no separate request payload. The details required for token are available in request headers and query parameters.

Response Elements

The following is an example of a response generated by the Authentication API. Token response for grant type ‘authorization_code‘:

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjM0NzU2MTcxNTYsInVzZXJfbmFtZSI6InVzZXJuYW1lX0plZXQiLCJzY29wZSI6WyJ3cml0ZSJdLCJqdGkiOiI5NzNkMDEyYi04NDVhLTQzMjEtYjJmNC0yNTdlMDFkZTcxZDQiLCJjbGllbnRfaWQiOiJ0ZXN0ciIsIlRva2VuX0luZm9ybWF0aW9uIjp7ImRhdGVUaW1lSXNzdWVkIjoiMjAxNi0xMC0wNCIsImF1dGhlbnRpY2F0aW9uTGV2ZWwiOiJBVVRIRU5USUNBVEVEIiwibWVtYmVyc2hpcE51bWJlciI6IjMwODE0NzEwMTA5OTM2MzEiLCJyZXF1ZXN0QXBwbGljYXRpb24iOiJBUEkiLCJyZXF1ZXN0ZWRQYXJ0bmVySWQiOiJ0ZXN0ciIsInByb2dyYW1tZUlkZW50aWZpZXIiOiJBVFJQIn19.rciZVcZGdRmPA66FGIDZzAeeHfSuxJ0n1Nac",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NzU3ODUzNjcsInVzZXJfbmFtZSI6InVzZXJuYW1lX0plZXQiLCJzY29wZSI6WyJ3cml0ZSJdLCJqdGkiOiJi ZDdjM2I1OC04N2IxLTRmYzctYTJhOC0zZTU3OTQ4MjQ3NWMiLCJjbGllbnRfaWQiOiJ0ZXN0ciIsImF0aSI6Ijk3M2QwMTJiLTg0NWEtNDMyMS1iMmY0LTI1N2UwMWRlNzFkNCJ9.KZnyldWK7yhE-vZaoYfD_r31qIdFK55C_eTE2bAArnA",
  "expires_in": 2000031788,
...Show more

The elements that make up the response message are detailed in the following table. The endpoint returns the response attributes in uppercase or lowercase ASCII characters as appropriate.

Exception Message Elements

Error message 1:

{
  "error": "unsupported_grant_type",
  "error_description": "Unsupported grant type: passwordw"
}

Error message 2:

{
  "error": "server_error",
  "error_description": "Request UnAuthorized"
}

This service returns standard OAuth 2.0 error messages. The exception message responses may be formatted in either upper or lower case.

Error Codes

All the errors from the Authentication service are returned in the standard OAuth 2.0 format shown above. This reports errors as a combination of parent error code and child error code.

The error codes for Authentication are shown in the following table:

User Friendly Error Codes

The following table describes the list of user friendly error message when the member tries to login using login page.