Authentication

Vaix supports two authentication methods, the Vaix method and the OAuth method.

Vaix method

In this method the API uses Bearer Tokens to allow access to the API. These tokens are created by VAIX and are user-specific.

OAuth method

In this method user has to generate an OAuth token and use this token as a Bearer token. Vaix will provide the client_id and the client_secret and the user using these has to generate the token.

A simple curl request

$ curl --request POST \\
  --url 'https://auth.sportradar.com/oauth/token' \\
  --header 'content-type: application/json' \\
  --data '{
    "grant_type": "client_credentials",
    "client_id": "{ClientId}",
    "client_secret": "{CLIENT_SECRET}",
    "audience": "api.vaix.ai"
  }'

Or in other case check this docs according your implementation.

For the staging environment use the https://stg-auth.sportradar.com as auth server and staging-api.vaix.ai as audience.

Use OAuth method

In order to use the OAuth method, the user has to pass the x-vaix-authentication-method=iam header in the request. Otherwise the default Vaix method will be used.

x-vaix-authentication-method: iam

Expiration Time

For the OAuth method the user is responsible to handle the token's expiration time. It is advised to store the token until its expiration time and when the token is about to be expired then the user has to generate again a new token.

The API expects for the Token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <USER-AUTH-TOKEN>

Proper token

Make sure to replace <USER-AUTH-TOKEN> with your personal Authorization Token

Backend integrations

Note that for backend integrations the Vaix method is deprecated, the OAuth method should be used.

Endpoint permissions

Notice that you need specific permissions in order to access each endpoint. If your token is valid but you don't have permissions for a specific endpoint then you will get a 403 FORBIDDEN response.

Check the Authorization and Packages sections for more details.

x-vaix-client-id header

You need to provide a custom x-vaix-client-id header when performing API requests. The header is required and provided with the authentication token.

Example of x-vaix-client-id header

In this example we assume that we require from the Bet Company customer to set the header, so the customer is expected to perform the request as:

$ curl --request GET \\
  --header x-vaix-client-id: bet_company \\
  --url 'https://api.vaix.ai/api/sports/offering/events'

Token types

For security reasons, the API supports two different token types, frontend and backend. An API request is considered a frontend request if it contains an Origin or a Referer header, otherwise it is classified as a backend request. Based on the request type the corresponding token type should be used, otherwise the request will fail with a 401 UNAUTHORIZED response.

Notice that when requesting a token you should specify the integration type in order to be provided with the appropriate token.

Authorized packages

The API defines a set of packages which correspond to permissions to access specific endpoint for the bearers of these packages.

VAIX will assign a set of packages to each user and as a result this user will be able to access only the endpoints whitelisted by these packages.

Notice that if the package corresponding to the endpoint you are calling is not activated for your account you will get a 403 error response.

What packages are enabled for my account?

You can find the packages that are enabled for your account by using the /api/info/whoami endpoint.