# 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 %}


---

# 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.betaramps.com/documentation-beta-ramps/api-guide/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.