> For the complete documentation index, see [llms.txt](https://docs.dextoros.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dextoros.app/connect-robots/keys-and-pairing.md).

# Keys and pairing

How pairing keys connect a robot, and how to rotate or revoke them.

{% hint style="warning" %}
**Draft.** Some details on this page are still being confirmed and may change. Questions? Email <info@dextoros.app>.
{% endhint %}

Every robot has its own **pairing key**. DextorOS writes it into the robot's `dextoros-connector.yaml` as `pairing_key`, and the robot uses it on its first connection.

{% hint style="danger" %}
Treat the pairing key like a password. Anyone with the connector file can connect as that robot. Don't commit it to a repository or share it in chat.
{% endhint %}

## Pairing states

| State                            | What it means                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------ |
| **Waiting for first connection** | The connector is generated but the robot hasn't connected yet.                 |
| **Handshake**                    | The robot has connected and DextorOS is checking its key.                      |
| **Live**                         | The robot is paired, has reported its capabilities and is streaming telemetry. |

## Rotate a key

Use **Rotate key** to replace a robot's key, for example if the connector file was shared by mistake.

{% hint style="warning" %}
Key rotated. The old key stops working, so reinstall the connector on the robot with the new file.
{% endhint %}

## Revoke a key

Use **Revoke key** to cut a live robot off. The robot disconnects and needs a new connector before it can connect again.

## Changes that need a reinstall

These changes return the robot to **Waiting for first connection**:

| Change            | What to do                                |
| ----------------- | ----------------------------------------- |
| Robot renamed     | Reinstall the connector to reconnect.     |
| Platform changed  | Reinstall the connector to reconnect.     |
| Transport changed | Reinstall the connector to reconnect.     |
| Key rotated       | Reinstall the connector with the new key. |
| Key revoked       | Generate a new connector and install it.  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.dextoros.app/connect-robots/keys-and-pairing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.