# Device API

## Update Public Key Endpoint

Use this endpoint to update the public key of a registered device. To ensure that only a genuine device can update its public key, the device has to authenticate by providing a private key JWT. Furthermore the device has to provide a proof of possession (PoP) object to demonstrate possession of the private key corresponding to the public key it tries to update.

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

## Refresh public key

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

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Private key JWT containing the new public key. |

#### Request Body

| Name                                  | Type   | Description                |
| ------------------------------------- | ------ | -------------------------- |
| pop<mark style="color:red;">\*</mark> | String | Proof of Possession object |

{% tabs %}
{% tab title="200: OK Successful update of the registered public key." %}

```json
{
    "Success": "Public key updated"
}
```

{% endtab %}

{% tab title="400: Bad Request The request format was incorrect." %}

```json
{
    // TODO
}
```

{% endtab %}

{% tab title="401: Unauthorized The private key JWT was missing or invalid." %}

```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. " %}

```json5
{
    "error": 
    {
        "code": 500,
        "status": "Internal Server Error",
        "request": "<REQUEST_ID>",
        "message": "An internal server error occurred, please contact the system administrator"
    }
}
```

{% 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 device is not allowed to update its public key." %}

```json
{
    "error": {
        "code": 403,
        "status": "Forbbiden",
        "request": "<REQUEST_ID>",
        "message": "Forbidden"
    }
}
```

{% endtab %}
{% endtabs %}


---

# 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://iothentix.gitbook.io/api-reference/reference/http-api-reference/device-api.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.