# 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

```bash
$ 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](https://auth0.com/docs/quickstarts) according your implementation.

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

{% hint style="info" %}

### 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.

```http
x-vaix-authentication-method: iam
```

{% endhint %}

{% hint style="info" %}

### 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.
{% endhint %}

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

```http
Authorization: Bearer <USER-AUTH-TOKEN>
```

{% hint style="info" %}

### Proper token

Make sure to replace `<USER-AUTH-TOKEN>` with your personal Authorization Token
{% endhint %}

{% hint style="info" %}

### Backend integrations

Note that for backend integrations the `Vaix` method is deprecated, the `OAuth` method should be used.
{% endhint %}

{% hint style="warning" %}

### 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.
{% endhint %}

## `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.

{% hint style="info" %}

### 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:

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

{% endhint %}

{% hint style="info" %}

### 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.
{% endhint %}

## 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.

{% hint style="info" %}

### 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.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportradar.com/personalization/overview/using-the-api/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.