Authentication and Client Secrets

Intended Usage

The Authentication APIs must only be accessed from behind a secure layer of an application, not exposed as part of an insecure, consumer-facing environment, such as via JavaScript in a web page

Authentication

All requests to the MX Reference Data API must be accompanied by an authorisation header and your client secret key.

Authorisation header

Complete the following steps to obtain an access_token for use in the authorisation header of each request to the MX Reference Data API.

1. If you do not have user credentials, contact us at [email protected] and request some.

   Note: We strongly recommend that you request user credentials for your application rather than a real person. If an account is based on a real person’s name and email address, you will not be able to monitor the email address or reset the password if that person is away or leaves your company. Instead, we recommend that you provide us with an application-specific username and a general email address that more than one person can monitor.

   For example: If your company were called FooTickets and you had a website and a mobile application, you might request the following separate credentials:
   Username: FooTickets_Web
   Email: [email protected]
   Username: FooTickets_Mobile
   Email: [email protected]

   Note: You can use one set of credentials to access multiple movieXchange APIs (MX Tickets and MX Showtimes, for example) – you do not need to create a set of credentials per API service. When you contact us to request credentials, please let us know which API services you want to access.

2. When you receive a user-account confirmation email, click on the link to verify your username and set a password.

   Note: These are API credentials and cannot be used to log in to moviexchange.com.

3. Decide on a client ID that uniquely identifies your organisation and application. This can be any string up to 50 characters long. If you have, for example, a website and a background task that checks for details offline, use the same username and password but two separate client IDs (for example: _Website and _OfflineUpdater). This is mostly to help us help you if there is a problem.

4. Once you have credentials (a username and password) use them, along with your client ID, to call the authentication API (example request can be seen in the documentation for the Token endpoint).

If authentication is successful, you will receive an access_token that can be sent in the Authorisation header to the other API endpoints together with the secret key. This access token is valid for the number of seconds specified in the expires_in property. The default is 43200 seconds, which is 12 hours. To ensure that you do not receive authorisation errors, we recommend that you refresh your access_token before the expiry time.

Client Secret

As part of the provisioning process for your account, you will receive a second email that contains your client secret key. This must be sent in the MX-Api-Client-Secret header for all API requests excluding those to the authentication API.

❗️

Important:

Never allow your client secret to become public; it is used to verify that communication with the API originated from your account.

Refresh Token

Refresh tokens are useful in situations where you need to re-authenticate but don't have access to the username and password originally used when you first authenticated. When the access token is about to expire, you can use the refresh token to retrieve a new access token and refresh token without having to ask for the username and password again.

The request to use a refresh token is very like the authenticate request, but rather than providing a username and password, it specifies the refresh token and a grant_type of refresh_token. The response it returns is similar to the authenticate request. This means that you will receive a new access token that you can use to call API endpoints and a new refresh token that you can use to refresh the access token when it expires.

As per our recommended usage statement, it is expected that applications which access the MX API will be server-based and therefore able to access the credentials required to obtain an access token whenever needed. Therefore, it is likely that refresh tokens will be of limited usage for MX API clients.

Note: A refresh token can only be used with the client_id it was issued for.