Authenticator Apps
An authenticator app is a container for OTP accounts. Each app belongs to an organization and can optionally be linked to an agent identity. You can think of it as your agent's virtual authenticator device.
Create authenticator app POST
POST /authenticator/appsCreate a new authenticator app. Optionally pass agent_handle to link the app to an identity on creation.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
agent_handle | string | No | Agent identity handle to link this app to. If omitted, the app is created unlinked. |
Request example
JSONResponse (201)
JSONError responses
| Status | Description |
|---|---|
| 403 | Organization ID missing from token |
| 404 | Agent identity not found |
| 409 | Identity already has an authenticator app |
Code examples
cURLList authenticator apps GET
GET /authenticator/appsList all non-deleted authenticator apps for your organization.
Response (200)
JSONCode examples
cURLGet authenticator app GET
GET /authenticator/apps/{id}Get a single authenticator app by ID.
Path parameters
| Parameter | Type | Description |
|---|---|---|
id | UUID | Authenticator app ID |
Response (200)
JSONCode examples
cURLDelete authenticator app DELETE
DELETE /authenticator/apps/{id}Soft-delete an authenticator app. This also unbinds the app from its identity (if linked) and soft-deletes all child accounts. Returns 204 No Content on success.
Path parameters
| Parameter | Type | Description |
|---|---|---|
id | UUID | Authenticator app ID |
Code examples
cURLAuthenticator app object
| Field | Type | Description |
|---|---|---|
id | UUID | Unique authenticator app identifier |
organization_id | string | Organization that owns this app |
identity_id | UUID | null | Linked agent identity ID, or null if unlinked |
status | string | Lifecycle status: active, deleted |
created_at | string | Creation timestamp (ISO 8601) |
updated_at | string | Last update timestamp (ISO 8601) |