This is a multi-page printable view. Click here to print.

Or, return to the page.

Getting Started

Tips and recommendations for new users of the AIR MILES API library.
Table of contents

It’s highly recommended you read through this entire section, before moving on to the API documentation; and make sure to review our AIR MILES glossary to better familiarize yourself with our terminology.

1 - AIR MILES Glossary

A collection of commonly used terms and acronyms within the AIR MILES program.
Term Definition
AM Cash Redemptions The process of collecting AIR MILES® from a Collector’s account to exchange for cash value in-store, or online from their Cash balance.
AMRP AIR MILES® Reward Program
AMRP Calculated In this method, AIR MILES® calculates the miles to be issued for each transaction. The APIs in this section handle all the calculations and logging themselves, which makes things easier for most businesses looking to integrate with the AIR MILES® Reward Program. Using this method ensures AIR MILES® takes care of all the logging and billing aspects of the service.
Batch Issuance The process of issuing AIR MILES® using daily batch files, to a Collector’s account when they make a purchase at your business.
Collector A member of the AIR MILES® Reward Program.
Issuer Code An “Issuer Code” is a UID (unique identifier) for a particular Partner.
Member Authentication Collector authentication using the Collector’s number and PIN.
Member Banner In-app graphical interface displaying relevant collector information such as collector name, program tier & Dream/Cash balances.
Offer Allows a collector the ability to earn AIR MILES® Reward Miles with the purchase of a particular good or service.
Offer Code An “Offer Code” is a UID (unique identifier) for a particular offer from a specific Partner.
Partner Authentication Refers to the Auth0 authentication for API access.
Partner Calculated In this method, the Partner is required to calculate how many Miles to issue to the Collector themselves, as well as keeping a detailed log of each transaction, so that it can be remitted to AIR MILES at a later date to facilitate billing and reconcile the accounts. This method is primarily used by larger businesses that need to keep a detailed log of all transactions and remit those transactions on their own time-schedule.
Real-Time Issuance The process of issuing (aka depositing) AIR MILES® within moments, to a Collector’s account when they make a purchase at your business.
TSOR The AIR MILES® Transaction System of Record (TSOR).

2 - Step 1: Determine App Type

Select the application type below that matches your own, to determine which “Authentication Flow” to use.

AIR MILES uses Auth0 for API user authentication. By identifying your application type, you can easily determine which authentication/authorization method you should be using. Besides the application type, other factors may play a role in deciding which authentication method you will use.

These could include:
The level of trust your users have in your application
The user experience you wish to deliver to your customers

Type A: Mobile & Single Page Applications

Integrate our API with a native mobile app (e.g., for iOS or Android), or a SPA (Single Page Application). This method uses the Authorization Code Flow with PKCE (proof key for code exchange).

Click the button below to request access to this authentication flow.

Sequence Diagram for Authorization Code Flow with PKCE

autonumber "<b>(0) "
skinparam sequenceMessageAlign direction
skinparam ParticipantPadding 20
!theme cerulean
actor "User" as U
participant "Mobile App" as A
collections "Auth0 Tenant" as A0
database "AMRP-API" as API
U -> A : Click login link
note right
Generates **code verifier**
and **code challenge**
end note
A -> A0 : Send "auth code" request + **code challenge** to ""**/authorize**""
A0 -> U : Redirect to login/authorization prompt
U -> A0 : Request user authentication/consent
A0 -> A : Create an **auth code**
A -> A0 : Send **auth code** + **code verifier** to ""**/oauth/token**""
note right
Auth server validates
the **code challenge**/
**code verifier**
end note
A0 --> A : Server responds with **id token** / **access token**
A -> API : Use the **access token** to make API calls to the server
note right: Note: Only API calls that are\nwithin the permitted scope.
API --> A : API responds with requested data

Type B: Regular Web Applications

Integrate our API with a standard web-server application that utilizes a client_id and client_secret (e.g., Express.js, ASP.NET etc.). This method uses the Authorization Code Flow.

Click the button below to request access to this authentication flow.

Sequence Diagram for Authorization Code Flow

sequenceDiagram
autonumber
participant U as User
participant A as Webpage
participant A0 as Auth0 Tenant
participant API as AMRP-API
U->>A: Click login link
A->>A0: Authorization Code request sent to "/authorize"
A0->>U: Redirect to login/authorization prompt
U->>A0: User authentication and consent
A0->>A: Create an Authorization Code
A->>A0: Send Authorization Code + Client ID + Client Secret to "/oauth/token"
A0->>A0: Auth Server validates Authorization Code + Client ID + Client Secret
A0->>A: Server responds with "ID Token" and "Access Token"
A->>API: Access Token used to make API calls (that are within the user's scope)
API->>A: API responds with requested data

Type C: Back-End Systems

Integrate our API with another API platform or a direct M2M (machine-to-machine) connection. (e.g., for CLIs, daemons, and back-end services). This method uses the Client Credentials Flow.

Click the button below to request access to this authentication flow.

Sequence Diagram for Client Credentials Flow

sequenceDiagram
autonumber
participant M as M2M App
participant A0 as Auth0 Tenant
participant API as AMRP-API
M->>A0: Authenticate with Client ID + Client Secret to "/oauth/token"
A0->>A0: Auth Server validates Client ID + Client Secret
A0->>M: Server responds with Access Token
M->>API: Access Token used to make API calls (that are within the user's scope)
API->>M: API responds with requested data

3 - Step 2: Engagement Process

A step-by-step guide to our engagement process, which includes certification and environment/access credentials.

Provided by the Partner (i.e., You)

Architecture overview diagram

Please provide us with an architecture overview diagram of your business systems.

See example diagram below:

Example architecture overview diagram

Data flow description for PII data

Provide a description of your Data Flows to ensure that any PII data is handled securely.

See example diagram below:

Example data flow diagram

Security Questionnaire

Follow the instructions below to complete the Security Questionnaire.

  1. Download the Excel spreadsheet using the link below.
  2. Fill out your answers in the provided cells.
  3. Save the file and email the completed questionnaire to partner support.

Provided by AIR MILES

AIR MILES partner contract

  • Includes the API Terms of Use.
  • Ongoing reviews of your solution by the Security and Compliance Team.

Obtaining environment & access credentials

  • Client/Secret keys for API access (available upon request).
  • IP white-list and SSL certificate requirements.
  • Test data environment, including sample Collector numbers, Offer Codes, Location Codes etc..
  • Access provided to our “Certification” environment (or ‘CERT’), for testing and development.
  • Load tests and other stress tests to be scheduled with AIR MILES integration specialists.

4 - Step 3: Best Practices & FAQs

Quick reference information to quickly answer your questions.

Best practices

Don’t hard code credentials.

Never allow credentials to be stored directly within your application code. While it can be convenient to test application code with hard-coded credentials during development this significantly increases risk and should be avoided.

Don’t use invalidated forwards or redirects.

An invalidated forward can allow an attacker to access private content without authentication. Invalidated redirects allow an attacker to lure victims into visiting malicious sites.

Implement an idle session timeout.

When a user is not active, the application should automatically log the user out. Be aware that Ajax applications may make recurring calls to the application effectively resetting the timeout counter automatically.

Invalidate the session after logout.

When the user logs out of the application session, corresponding data on the server must be destroyed. This ensures that the session cannot be accidentally revived.

Store user passwords using a strong, iterative, salted hash.

User passwords must be stored using secure hashing techniques with strong algorithms like PBKDF2, bcrypt, or SHA-512.

Limit the use and storage of sensitive data.

Conduct an evaluation to ensure that sensitive data is not being unnecessarily transported or stored. Where possible, use tokenization to reduce data exposure risks.

Frequently asked questions

What are my responsibilities as a Partner?

Providing the following will help accelerate the on-boarding process.

  • Architecture overview showing how APIs will be consumed in your environment
  • Data flows ensuring PII data is handled securely
  • Completed Security Questionnaire

For more information, please read Step 2: Engagement Process.

Where do I get access credentials and information on your API environments?

To request these details, please contact us after you have completed the steps listed in our Engagement Process.

What information will you be providing me once I have completed the steps outlined in your Engagement Process?

Once you have completed the requested information in our Engagement Process, you will be provided with:

  • Client ID and secret keys for accessing the APIs
  • IP white-listing and SSL certification
  • Sample data (e.g., Collector numbers, sample offers, and location data) for testing and development
  • Access to our certification environment for testing and development
  • Scheduled load testing and other necessary stress tests