---
description: >-
  The token API is for requesting access tokens issued by our IoT identity
  provider.
---

# Token API

## Token Endpoint

Use this endpoint to request a new access token by authenticating with a private key JWT.

{% hint style="info" %}
For additional details about the JWT visit our [developer guide](https://iothentix.gitbook.io/developer-guide/json-web-token-jwt/authentication-jwt).
{% endhint %}

## Request a token

<mark style="color:green;">`POST`</mark> `coaps://iot-idp.demo.coap-apps.iothentix.io/as/token`

Request an access token by authenticating with a signed JWT.&#x20;

#### Request Body

| Name                                             | Type   | Description                                        |
| ------------------------------------------------ | ------ | -------------------------------------------------- |
| client\_id<mark style="color:red;">\*</mark>     | String | Client ID of the registered OAuth client.          |
| scope                                            | String | Request a scope to be present in the access token. |
| client\_secret<mark style="color:red;">\*</mark> | String | Private key JWT.                                   |

{% tabs %}
{% tab title="201: Created Successful token request" %}
```json
{
  "access_token": "<ACCESS_TOKEN>"
}
```
{% endtab %}

{% tab title="401: Unauthorized The private key JWT was missing." %}
```json
{
    "error":"UNAUTHORIZED",
    "error_uri":"iot-idp.demo.apps.iothentix.com",
    "error_description":"The request could not be authorized"
}
```
{% endtab %}

{% tab title="400: Bad Request The request format was incorrect." %}
```
// Some code
```
{% endtab %}

{% tab title="500: Internal Server Error Internal error in the IdP infrastructure." %}
```json
{
    "error": 
    {
        "code": 500,
        "status": "Internal Server Error",
        "request": "<REQUEST_ID>",
        "message": "An internal server error occurred, please contact the system administrator"
    }
}
```
{% endtab %}

{% tab title="403: Forbidden The private key JWT was invalid." %}
```json
{
    "error": "FORBIDDEN",
    "error_uri": "iot-idp.demo.apps.iothentix.com",
    "error_description": "The requested action was forbidden"
}
```
{% endtab %}

{% tab title="405: Method Not Allowed The requested method is not allowed for this resource." %}

{% endtab %}
{% endtabs %}

## Renew Token Endpoint

Use this endpoint to renew the access token based on a previously issued access token.

## Refresh the token

<mark style="color:green;">`POST`</mark> `coaps://iot-idp.demo.coap-apps.iothentix.io/as/renew/token`

Request a new access token by authenticating with a previously issued access token.

#### Request Body

| Name                                         | Type   | Description                              |
| -------------------------------------------- | ------ | ---------------------------------------- |
| client\_id<mark style="color:red;">\*</mark> | String | Client ID of the registered OAuth client |
| token<mark style="color:red;">\*</mark>      | String | Access token issued by the IoT provider  |

{% tabs %}
{% tab title="201: Created Successful token refresh request " %}
```javascript
{
  "access_token": "<ACCESS_TOKEN>"
}
```
{% endtab %}

{% tab title="400: Bad Request " %}
```javascript
{
    // Response
}
```
{% endtab %}

{% tab title="500: Internal Server Error Internal error in the IdP infrastructure. " %}
```javascript
{
    "error": 
    {
        "code": 500,
        "status": "Internal Server Error",
        "request": "<REQUEST_ID>",
        "message": "An internal server error occurred, please contact the system administrator"
    }
}
```
{% endtab %}

{% tab title="403: Forbidden " %}
```javascript
{
    "error": "FORBIDDEN",
    "error_uri": "iot-idp.demo.apps.iothentix.com",
    "error_description": "The requested action was forbidden"
}
```
{% endtab %}
{% endtabs %}
