Introspect the principal behind the agent key

GET

/v1/auth/me

• Production
• Local

Requires only a valid key (any scope), so an agent can always read its own authority.

Authorizations

• AgentKey

Responses

200

The verified principal.

The verified principal behind an agent key. org_id/project_id are the FIXED org/project the key is bound to (resolved from the stored key, never client input). There is NO mutable project selector for a scoped key; whoami is the canonical project-visibility surface; project selection happens when the human/admin issues the enrollment token or agent key.

object

signup_starter

Recover the single system-prepared, agent-owned practice review. A preparing status means the durable worker has not finished; do not submit another hello. Feedback and revisions belong to this review. The coaching example is optional and is not authority to save a rule until the human submits it as feedback.

object

review_id

required

string

review_path

required

Account-aware console entry path preserving this review.

string

status

required

Pending_activation or preparing until a review exists; otherwise its current review state.

string

coaching_prompt

required

Optional human feedback to copy into the review discussion.

string

connection

Explicit consent bound to one connection; token refresh never extends grant expiry. The immutable capability profile is a distribution ceiling, not an account role. Full preserves existing permissions; assistant permits only selected inboxes or one project and excludes commerce, administration, delegation, credentials, quotas and webhooks. Independently created credentials on the full profile retain their own lifetimes.

object

id

required

string

capability_profile

Server-derived immutable ceiling. An absent legacy value means full compatibility, never new full-account permission.

string

Allowed values: full assistant

authorizer_id

required

string

client_id

required

string

name

required

string

identity

required

string

Allowed values: personal_assistant dedicated_agent

agent_id

string

agent_org_id

string

reach

required

string

Allowed values: inboxes project organization full_account

org_id

string

project_id

string

inbox_ids

Array<string>

<= 100 items

scopes

required

Array<string>

created_by_connection_id

Creation provenance; parent expiry and revocation do not cascade.

string

consent_version

string

created_at_ms

required

integer format: int64

expires_at_ms

required

Fixed grant deadline in Unix milliseconds. Zero means until revoked.

integer format: int64

revoked_at_ms

required

integer format: int64

last_used_at_ms

integer format: int64

auth_method

string

Allowed values: oauth agent_key connection

key_tier

string

Allowed values: org project inbox

inbox_scope

string

Allowed values: agent_owned organization_subtree single_inbox inboxes project organization full_account

inbox_id

Canonical inbox bound to a single-inbox credential.

string

connection_status

string

Allowed values: connected

summary

Plain-language connection result and limits.

string

agent_name

string

organization_name

string

project_name

string

capabilities

Granted permissions, not plan capacity or permission to bypass mail review.

object

read_domain_status

boolean

connect_owned_domains

boolean

create_inboxes

boolean

read_inboxes

boolean

submit_mail_for_review

boolean

request_purchases

boolean

administer_account

boolean

approve_requests

boolean

create_credentials

boolean

customer_id

string

org_id

The fixed org the key is bound to.

string

project_id

The fixed project the key is bound to.

string

agent_id

string

key_id

string

scopes

Array<string>

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

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean