Authentication API Documentation

v1Showing ATRP 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 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.

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

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
NameData typeDescription
response_type
Required
StringValue must be set to 'code' always. This signifies that the partner is attempting to initiate the token process using OAuth's authorization_code grant type
Format: String
redirect_uri
Optional
StringRepresenting the endpoint to which the authorization server sends the auth code as query parameter. The redirect uri should match with configured uri. Different redirect uris are configured for different partners.
Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (
client_id
Required
StringClient Id specific to each partner. This will have been provided during the partner on-boarding process.
Format: Alphanumeric
scope
Optional
String
state
Optional
StringTo maintain state between the request and call-back to avoid the CSRF (Cross-Site Request Forgery) attacks.
Format: Alphanumeric
brandName
Optional
StringTo display the partner logo in the login pages
Format: Alphabetic only
Programme-Identifier
Required
StringThe identifier for the loyalty programme to which the member belongs. This will have been provided during the partner on-boarding process.
Format: Alphabetic only. Max length: 20
Business-Context-Identifier
Required
StringContext through which the information is coming. The value assigned to the partner. Once the value was passed it should be used when calling all other endpoints which required business- context-identifier. Currently not in use, business-context-identifier value will have been provided during the partner on-boarding process which should be used when calling other endpoints.
Format: Alphabetic only. Max length: 50

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
NameData typeDescription
grant_type
Required
StringThis grant type allows partner to use their credentials to retrieve an access token directly, which allows access to resource under partner’s control. Must be set to ‘authorization_code’.
Format: Enumeration
code
Required
StringThis is the authorization code previously retrieved from OAuth authorization server in auth code for partner login page scenario. Authorization code can only be used once to authenticate a member.
Format: Alpha numeric
client_id
Optional
StringClient Id specific to each partner. This will have been provided during the partner on-boarding process.
Format: Alphanumeric
scope
Optional
StringProviding scope is only necessary when resetting the password or retrieving the username of a member. The values of the scope can be set to “reset_password” or “retrieve_username”.
Format: Enumeration

Authentication Headers for grant Type: Authorization_code

NameData typeDescription
business-context-identifier
Required
StringChannel through which the information is coming. The value assigned to the partner.
Format: Alphabetic only. Min length: 1, Max length: 50
programme-identifier
Required
StringThe identifier for the loyalty programme to which the member belongs.
Format: Alphabetic only
authorization
Required
StringThis is base64 encoded combination of client Identifier and Partner Secret. This information is shared as part of partner on-boarding.
Format: Base 64 encoded
accept
Optional
StringThe Accept request-header field is used to specify certain media types which are acceptable for the response. Only supported value is “application/json”
Format: application/json
x-forwarded-for
Optional
StringThe IP address of the end customer.
Format: Valid IP address

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,

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.

NameData TypeDescription
token
Present
Complex type 1..1Token represents credentials used to access protected resources.
token.access_token
Present
StringAn access token is a string representing an authorisation issued to the client. This token must be provided to secured API calls like update security profile, retrieve member etc.
Format: JWT Token
token.token_type
Present
StringType of the token generated for the partner
Format: Enumeration
token.refresh_token
Conditional
StringA refresh token is a string representing an authorisation issued to the client for obtaining a new access token. Because refresh tokens are typically long-lasting credentials used to request additional access tokens, the refresh token is bound to the client to which it was issued.
Format: JWT Token
token.expires_in
Present
NumberThe time interval after which the token will expire. The unit in seconds
Format: Numeric
token.scope
Present
StringProviding scope is only necessary when resetting the password or retrieving the username of a member. The values of the scope can be set to “reset_password” or “retrieve_username”.
Format: Enumeration
token.jti
Present
NumberThis represents jwt token identifier
Format: Numeric
token.Token Information
Present
Complex type 1..1Additional information provided along with the token.
token.token_Information.dateTimeIssued
Present
DateThe date when the token was issued to the partner.
Format: yyyy-mm-dd
token.token_Information.authenticationLevel
Present
StringThis describes the authentication status. Will always be ‘AUTHENTICATED’
Format: Enumeration
token.token_Information.requestApplication
Present
StringThe application which requested the token. Business-Context- Identifier header is set as requestApplication.
Format: Alphabets only
token.token_Information.membershipNumber
Conditional
StringMembership number is the member identifier who’s credentials are authorised for obtaining the access token. This is only applicable for password grant type.
Format: Min length = 16. Max Length = 24. Numeric only
token.token_Information.requestedPartnerId
Present
StringThis represents partner identifier who requested the token
Format: Min length: 8. Max length: 20. Alphanumeric
token.token_Information.programmeIdentifier
Present
StringIdentifier specifying the loyalty programme the member belongs to. Value will be the same which were provided in the request header.
Format: Alphabets only

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.

NameData typeDescription
error
Required
StringError code. Example: server_error
Format: Alphabetic plus underscore (
description
Conditional
StringDescription of the error. Example: Request UnAuthorized
Format: Alphanumeric with special characters colon (:), space ( ).
scope
Conditional
StringDescribes possible scopes of grant type client credentials. Will be present when the requested scope is invalid, unknown, or malformed. Example: read
Format: Alphanumeric

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:

Http Status CodeDescription
400
Invalid_request
The request is missing a required parameter, includes an invalid parameter value
401
unauthorized
The client is not authorised to request an access token using this method
401
access_denied
The resource owner or authorisation server denied the request
400
invalid_scope
The requested scope is invalid, unknown, or malformed
500
server_error
The authorisation server encountered an unexpected condition which prevented it from fulfilling the request
500
temporarily_unavailable
The authorisation server is currently unable to handle the request due to a temporary overloading or maintenance of the server
400
unsupported_grant_type
Provided grant_type is invalid
400
Invalid_grant
Provided Auth code is already used or incorrect
401
Invalid_client
Provided client id doesn’t match to the authentication information specified in headers.

User Friendly Error Codes

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

Error ScenarioError Message
Multiple attempts for a usernameYour details have not been recognised, please try again or update them at avios.com.
Invalid username.passwordYour details have not been recognised, please try again or update them at avios.com.
System Unavailable.Invalid security testWe seem to be experiencing some difficulties. Please try again later.
Username field is blankPlease enter your username.
Password field is blankPlease enter your password.
Password and Username fields are blankPlease enter your username. Please enter your password.
Invalid format of Username.PasswordYour details have not been recognised, please try again or update them at avios.com.
Invalid format of IP AddressWe seem to be experiencing some difficulties. Please try again later.