---
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. &#x20;

{% 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).&#x20;
{% endhint %}

## Request a token

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

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

#### Headers

| Name                                            | Type | Description     |
| ----------------------------------------------- | ---- | --------------- |
| Authorization<mark style="color:red;">\*</mark> |      | Private key JWT |

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

{% tabs %}
{% tab title="200: OK Successful token request." %}
```json
{
    "access_token": "<ACCESS_TOKEN>",
    "expires_in": 3599,
    "scope": "<REQUESTED_SOCPE>",
    "token_type": "bearer"
}
```
{% endtab %}

{% tab title="401: Unauthorized The private key JWT was missing." %}
```json
{
    "error": {
        "code": 401,
        "status": "Unauthorized",
        "request": "<REQUEST_ID>",
        "message": "The request could not be authorized"
    }
}
```
{% endtab %}

{% tab title="400: Bad Request The request format was incorrect." %}
```json
{
    "error": {
        "code": 400,
        "status": "Bad Request",
        "request": "<REQUEST_ID>",
        "message": "Bad Request"
    }
}
```
{% 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="429: Too Many Requests To many requests within the rate limit period." %}
```json
{
    "error": 
    {
        "code": 429,
        "message": "Slow down",
        "status": "Too Many Requests"
    }
}
```
{% endtab %}

{% tab title="404: Not Found The resource could not be found or the wrong HTTP method was used." %}
```json
{
    "error": {
        "code": 404,
        "status": "Not Found",
        "request": "<REQUEST_ID>",
        "message": "The requested resource could not be found"
    }
}
```
{% endtab %}

{% tab title="403: Forbidden The private key JWT was invalid." %}
```javascript
{
    "error": {
        "code": 403,
        "status": "Forbbiden",
        "request": "<REQUEST_ID>",
        "message": "Forbidden"
    }
}
```
{% 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> `https://iot-idp.demo.apps.iothentix.io/as/renew/token`

Request a new access token by authenticating with a previously issued access token.&#x20;

#### Headers

| Name                                            | Type   | Description                             |
| ----------------------------------------------- | ------ | --------------------------------------- |
| Authorisation<mark style="color:red;">\*</mark> | String | Access token issued by the IoT provider |

#### Request Body

| Name                                         | Type   | Description |
| -------------------------------------------- | ------ | ----------- |
| client\_id<mark style="color:red;">\*</mark> | String |             |

{% tabs %}
{% tab title="200: OK Successful token renew request ." %}
```json
{
    "access_token": "<ACCESS_TOKEN>",
    "expires_in": 3599,
    "scope": "REQUESTED_SOCPE",
    "token_type": "bearer"
}
```
{% endtab %}

{% tab title="401: Unauthorized The previously issued access token is invalid or missing." %}
```json
{
    "error": 
    {
        "code": 401,
        "status": "Unauthorized",
        "request": "<REQUEST_ID>",
        "message": "The request could not be authorized"
    }
}
```
{% 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 previously issued access token is not allowed to renew the access token." %}
```json
{{
    "error": {
        "code": 403,
        "status": "Forbbiden",
        "request": "<REQUEST_ID>",
        "message": "Forbidden"
    }
}
```
{% endtab %}

{% tab title="429: Too Many Requests To many requests within the rate limit period." %}
```json
{
    "error": {
        "code": 429,
        "message": "Slow down",
        "status": "Too Many Requests"
    }
}
```
{% endtab %}

{% tab title="404: Not Found The resource could not be found or the wrong HTTP method was used." %}
```json
{
    "error": {
        "code": 404,
        "status": "Not Found",
        "request": "<REQUEST_ID>",
        "message": "The requested resource could not be found"
    }
}
```
{% endtab %}
{% endtabs %}
