Create a project manager key from direct human consent

POST

/v1/admin/orgs/{org_id}/projects/{project_id}/manager-keys

• Production
• Local

Requires a signed-in human with current organization owner or admin authority. No prior OAuth connection is needed. The key is limited to this project, with persona management, worker credential delegation, inbox creation/read/deletion, and domain read permissions. Sending is opt-in. The API-audience secret is shown once, has its own expiry, and is managed through Connections. Worker credentials survive its expiry or ordinary revocation; use include_workers to revoke the whole team. Connections must use createConnectionCredential instead.

Authorizations

• ClerkSession

Parameters

Path Parameters

org_id

required

string

project_id

required

string

Request Body ^required

object

name

required

string

>= 1 characters <= 100 characters

duration

required

string

Allowed values: 24h until_revoked

allow_send

boolean

Responses

201

Key created. The response is not cacheable; store the secret now.

object

connection

required

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

credential

required

string

resource

required

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.