> For the complete documentation index, see [llms.txt](https://docs.betaramps.com/documentation-beta-ramps/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.betaramps.com/documentation-beta-ramps/api-guide/authentication.md).

# Authentication

When sending your requests, you must include an OAuth 2 bearer authentication Access token in your request's Authorization HTTP header field of your request.  

<figure><img src="/files/bWfk2xkKAosWmvPUuxCb" alt="Authentication diagram"><figcaption></figcaption></figure>

### Request Access Token

## Get a new access token&#x20;

<mark style="color:green;">`POST`</mark> `https://live.betaapp.com/v1/auth/token`

Use this endpoint to obtain an access token. After a successful request, save the token, as you might need it to communicate with our API in the future.

#### Headers

| Name                                           | Type   | Description      |
| ---------------------------------------------- | ------ | ---------------- |
| Content-type<mark style="color:red;">\*</mark> | String | application/json |
| accept<mark style="color:red;">\*</mark>       | String | application/json |

#### Request Body

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| client\_id<mark style="color:red;">\*</mark>     | String | The ID provided by Beta |
| client\_secret<mark style="color:red;">\*</mark> | String | Your secret             |

{% tabs %}
{% tab title="200: OK Successful authentication. " %}
The response will return a new access token, a Refresh token and the number of remaining seconds that the token is valid for.&#x20;

```
{
"access_token": "ghjdfknrgkdFGHJBKnlefwkbjvbfmsdfdvsjhdbGCFGHJBK",
"expires_in": 86400,
"token_type": "Bearer",
"refresh_token": "dg4yu53mvyui24nmvdyui248934m245m65o3245657676gdkd",
}
```

{% endtab %}

{% tab title="400: Bad Request Server could not read the request." %}

```
{
"ERROR"
}
```

{% endtab %}

{% tab title="401: Unauthorized Credentials are invalid." %}

```
{
"ERROR": "access_denied"
"error_description": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
Each token is a JWT that contains an expiration time. We will return the same Access token to you each time you request one, until it expires. After an Access token expires, you must obtain new token from the authentication endpoint.&#x20;
{% endhint %}

**Request Example:**

{% code lineNumbers="true" fullWidth="false" %}

```json
curl -X 'POST' \
  'https://live.betaapp.com/v1/auth/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "7DFGaTDiBailk...Lb7A",
  "client_secret": "mM398fj-A9Me9dlkszP...Myd3-eJWQ"
}'
```

{% endcode %}

**Response Example:**

{% code lineNumbers="true" fullWidth="false" %}

```json
{
"access_token":"Mn37fJgGciOiJSm3Isd7kjFnR5cCI6IsdFFkbCIsImtp..."
"expiration":86400
}
```

{% endcode %}

{% hint style="info" %}
When calling our APIs, you must include the word "**Bearer**" before you include the token value.
{% endhint %}

### Revoke Token

## Revoke token&#x20;

<mark style="color:green;">`POST`</mark> `https://live.betaapp.com/v1/auth/revoke`

This endpoint is used to revoke an access token from our cache. By revoking the token you can request a new one with the '/auth/token' endpoint

#### Headers

| Name                                           | Type   | Description      |
| ---------------------------------------------- | ------ | ---------------- |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json |
| accept<mark style="color:red;">\*</mark>       | String | application/json |

#### Request Body

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| client\_id<mark style="color:red;">\*</mark>     | String | The ID provided by Beta |
| client\_secret<mark style="color:red;">\*</mark> | String | Your secret             |

{% tabs %}
{% tab title="200: OK Success" %}

```
  {
   "status": "Success",
  }
```

{% endtab %}

{% tab title="400: Bad Request Server could not read the request " %}

```
  {
   "ERROR"
  }
```

{% endtab %}

{% tab title="401: Unauthorized Credentials are invalid." %}

```
{
"ERROR": "access_denied"
"error_description": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

If you send an expired Token to Beta, you will receive a 401 error, your integration *must* stop using this token and must request a new token to avoid receiving additional 401 errors.

**Request Example:**

{% code lineNumbers="true" fullWidth="false" %}

```json
curl -X 'POST' \
  'https://live.betaapp.com/v1/auth/revoke' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "7DFGaTDiBailk...Lb7A",
  "client_secret": "mM398fj-A9Me9dlkszP...Myd3-eJWQ"
}
```

{% endcode %}

**Response Example:**

{% code lineNumbers="true" fullWidth="false" %}

```json
{
"status": "Success"
}
```

{% endcode %}