API Quickstart

Authenticating against the API

Most of the exposed endpoints are protected through the OAuth2 protocol. As such, in order to access them, authentication is required. The required credentials to communicate with the secured endpoints are expressed as “bearer” tokens. They should be sent in a Authorization request header.

Scopes

API endpoints protect themselves by requiring the token to be decorated with specific scopes. As such, when requesting a token, the user must explicitly describe the scopes that this token should grant access to.

Current list of valid scopes:

  • urn:axa.assistance.travel.countries.read_only
  • urn:axa.assistance.travel.countries.alerts.read_only
  • urn:axa.assistance.travel.policies.creation_request
  • urn:axa.assistance.travel.policies.quote_request
  • urn:axa.assistance.health.providers.read_only

Generating a token

A token can only be generated from your client_id and client_secret per application identifiers. Those can easily be retrieved through the developer portal, (provided you’re signed in when accessing this link).

Please note that a token is a sensitive piece of information. Any communication performed with the API using this token will be considered done with your consent and on your behalf. As such, consider it like a secret password and apply all the possible measures to protect it from theft or leak.

Upon generation, a token may also come along with an expiration time. Make sure you generate a new one before it expires.

Tree kinds of OAuth2 grant types are supported.

Authorization Code Grant Resource Owner Password Credentials Grant Client Credentials Grant

Revoking a token

Would your token be compromised, you should revoke it to ensure it cannot be used on your behalf. First, make sure to generate a new one and update your production code to avoid any downtime for your users.

Some token may be generated without an expiration time. Although the token won’t indeed expire by itself, it’s a recommended practice to regenerate it periodically.

Required parameters:

  • client_id
  • client_secret
  • token

Request:

curl -X POST 'https://rest.axa-assistance.com/oauth/token/revoke' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-u '<client_id>:<client_secret>' \
-d 'token=<token>'

Response:

200 Ok

Leveraging the API

Once you’ve got a token, leveraging the API is quite easy. Navigate to https://developers.axa-assistance.com/docs, browse the API documentation and invoke it by adding an Authorization header to the request.

Required parameters:

  • token

Request:

curl -X GET 'https://rest.axa-assistance.com/travel/v1/countries' \
-H 'Authorization: Bearer <token>'

Response:

200 Ok
[
  {
    "id":"af", "label":"Afghanistan"
  },
  {
    "id":"ax", "label":"Aland Islands"
  },
  {
    ... snipped for brevity...
  },
  {
    "id":"zm", "label":"Zambia"
  },
  {
    "id":"zw", "label":"Zimbabwe"
  }
]

Troubleshooting

We strive to keep bugs out of our codebase and provide you with the best possible service. However, would you encounter any issue, please let us know about it.

Drop us an email at api.move@axa-assistance.com. We’ll be happy to support you!

In order to help us troubleshoot your issue more easily, please send us the output of the following command. This way we’ll know for sure which deployed version is causing you some pain.

Request:

curl -X GET 'https://rest.axa-assistance.com/version'

Response:

{
    "built-at": "2016-03-16T15:12:15Z",
    "commit-sha": "badc0ffee1deabeeffaceb00b00fa57ace5f00d1"
}

Online Resources

Github