Authorize a new connection grant

POST

/v1/admin/connection-authorizations/{authorization_id}/approve

• Production
• Local

Authorizations

• ClerkSession
• AgentKey
  account:admin

Parameters

Path Parameters

authorization_id

required

string

Request Body ^required

Use the authorization response’s server-derived allowed_reaches and allowed_scopes. Assistant authorizations permit inboxes or project reach only. The profile cannot be supplied or widened by this payload. When supported and requested by the client, openid and email require explicit consent and must be retained in scopes; they disclose the authorizing human’s identifier and verified email, not an agent mailbox, and grant no business action. The extrovert:connect handshake never implicitly grants identity scopes.

object

name

required

string

<= 100 characters

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

Explicit action and requested identity scopes within the server-derived profile ceiling.

Array<string>

<= 64 items

duration

Full account control defaults to 24h.

string

Allowed values: 24h until_revoked

full_control_confirmed

Required explicit consent for full account control including self-approval and lasting created credentials.

boolean

Responses

201

Success

object

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

redirect_url

Registered OAuth callback with a single-use PKCE authorization code.

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

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

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

403

Authenticated but lacking the required scope, or out of quota.

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

404

Resource not found.

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

503

Connection authorization is not enabled.