Verify a signup code and upgrade to a full-permission key

POST

/v1/agent/verify

• Production
• Local

Requires the verification-only signup:verify key. Atomically revokes it and returns a new full-permission key, activates the free account and its free.extrovertmail.com inbox, and returns copy-ready MCP read_messages/get_message/wait_for_email calls on success.

Authorizations

• AgentKey
  signup:verify

Request Body ^required

object

otp

required

string

Responses

200

Verified; full-permission key issued.

OTP verification activates the free account and returns the replacement full-permission key plus the ready free.extrovertmail.com inbox; the verification-only bootstrap key was revoked atomically. The inbox quickstart makes the response a self-contained handoff after a process restart or context compaction.

object

agent_id

required

string

agent_key

required

New full-permission key

string

key_prefix

required

string

scopes

required

Array<string>

address

required

The signup inbox, ready for immediate use.

string format: email

verified

required

boolean

message

required

string

mailbox_quickstart

required

MCP-first, read-only next calls for the verified signup inbox. Use these instead of inventing REST routes or parsing raw HTTP response files.

object

inbox

required

string format: email

list_mail

required

A copy-ready MCP tool call for ordinary mailbox use.

object

tool

required

string

Allowed values: read_messages get_message wait_for_email

arguments

required

object

key

additional properties

any

read_message

required

A copy-ready MCP tool call for ordinary mailbox use.

object

tool

required

string

Allowed values: read_messages get_message wait_for_email

arguments

required

object

key

additional properties

any

wait_for_mail

required

A copy-ready MCP tool call for ordinary mailbox use.

object

tool

required

string

Allowed values: read_messages get_message wait_for_email

arguments

required

object

key

additional properties

any

org_claim_token

One-time, email-bound owner claim seed for the signup org. Present only on a fresh signup. In the console, sign in with the verified email and call GET /v1/admin/me to find the matching pending_signup_claims entry. Then POST /v1/admin/signup-claims/{claim_id}/accept to bind that identity to the signup org as owner.

string

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

403

Free signup verification is temporarily paused (signup_disabled).

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

503

Signup availability could not be determined (signup_gate_unavailable).

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope