---
title: "Exchange a sign-in code for an API key"
method: POST
path: "/v1/agent_auth/verify_code"
tags: ["Authentication"]
---

# Exchange a sign-in code for an API key

`POST /v1/agent_auth/verify_code`

## Request

- Base URL: `https://api.revdoku.com`
- URL: `https://api.revdoku.com/v1/agent_auth/verify_code`
- Auth: none required

Creates an AI agent connection for an account owner or administrator. Accounts with two-factor authentication must use browser sign-in.

## Request body

- object
  - `email` string, email, required
  - `code` string, required: Six digits; spaces are ignored.
  - `label` string: Connection name shown in Account access.
  - `permission_scope` 'mailbox_read' | 'mailbox_write' | 'mailbox_admin'
  - `mailbox_access` 'all' | 'selected'
  - `mailbox_ids` string[]: Required when mailbox_access is selected.
  - `mailbox_permissions` object: Optional access per selected mailbox ID: read or write. Without an entry, a mailbox gets write, or read when permission_scope is mailbox_read.
  - `account_id` string: Select another granted account for this request.
  - `reason` string, nullable: Optional purpose for this action. AI agents should explain intentional reads and changes when known; omit when unknown. Do not include secrets, file contents, or transcripts.

## Response `201`

Created

- object
  - `success` true, required
  - `data` AgentConnection, required: A new API key for an AI agent or the CLI. Store api_key securely; it is shown only once.
    - `api_key` string, required
    - `account_id` string, required
    - `account_name` string
    - `scope` 'mailbox_read' | 'mailbox_write' | 'mailbox_admin', required
    - `mailbox_access` 'all' | 'selected'
    - `mailbox_ids` string[]
    - `mailbox_permissions` object
    - `account_connection_limits` object
    - `expires_at` string, date-time, nullable
    - `manage_access` object
    - `mailboxes` object[]
    - `guidance` string

## Other responses

- `default`: Request failed. See error.code. Any 429 or 503 response with Retry-After (for example 503 EMAIL_LABELING_PENDING or 503 EMAIL_INDEX_BUILDING): wait that many seconds, then try the read again. 429 EMAIL_SEND_RATE_LIMITED has no Retry-After. Never retry EMAIL_LOOP_DETECTED.

---

[API](https://skmtc.dev/revdoku/apis/revdoku-api.md) · [All operations](https://skmtc.dev/revdoku/apis/revdoku-api/llms.txt) · [OpenAPI document](https://skmtc.dev/revdoku/apis/revdoku-api/revisions/3ff4e2540a8b?raw)