---
title: "Pairing"
url: "https://control.actana.ai/docs/pairing"
description: "Enrollment by one-time code: mint on the Core, compare the fingerprint, redeem from the Panel, CLI, or SDK."
updated: 2026-09-01T09:03:03+00:00
---

Enrollment is a short code the operator carries. The code is not a credential: one certificate issuance, then worthless. The client's private key is born on the client and never crosses the wire. There is no registration blob to paste and no `actana core add`.

Both ends live in one `actana` binary. [`actana pair new`](/docs/pairing/create-a-pairing-code) runs **on the Core** and mints the code. The client spends it — [`actana core pair`](/docs/pairing/cli-pairing) on the machine being paired, [**Add a Core**](/docs/pairing/panel-pairing) in the Panel, or [`pairWithCore`](/docs/pairing/sdk-pairing) from a program.

Since 0.4.3, `pair new` at a terminal prints a **handout**: the code, fingerprint, session and expiry in one framed block, with the Panel steps and a ready-to-paste `actana core pair` command — every value already filled in — underneath. Carrying the four fields by hand still works; you just rarely have to.

The one manual step that remains is the point of the design: compare the [CA fingerprint](/docs/pairing/how-pairing-works#the-ca-fingerprint) **before** the code is sent.

```mermaid
sequenceDiagram
  participant Op as Operator
  participant Core
  participant Client as Client
  Op->>Core: actana pair new
  Core-->>Op: handout — code, fingerprint, session, expiry
  Op->>Client: paste the command (or carry the fields)
  Client->>Core: identify (sends nothing)
  Core-->>Client: CA in the handshake
  Client->>Op: show fingerprint
  Op->>Client: confirm match
  Client->>Core: redeem CSR with the code
  Core-->>Client: endpoint, CA, client cert, bearer
```

## In this section

- [How Pairing Works](/docs/pairing/how-pairing-works) — the protocol: mint, first contact, the fingerprint, redeem, refusals.
- [Create a Pairing Code](/docs/pairing/create-a-pairing-code) — `actana pair new`, the handout, and the code lifecycle: list, revoke, rotate.
- [Actana CLI Pairing](/docs/pairing/cli-pairing) — `actana core pair` on the machine being paired.
- [Panel Pairing](/docs/pairing/panel-pairing) — **Add a Core**, and the first-run wizard.
- [SDK Pairing](/docs/pairing/sdk-pairing) — `pairWithCore` from `@actana/sdk`.
- [Pairing Troubleshooting](/docs/pairing/troubleshooting) — what each refusal means.