--- title: "Get API Key" method: GET path: "/v0/api-keys/{api_key_id}" tags: ["api-keys"] --- # Get API Key `GET /v0/api-keys/{api_key_id}` ## Request - Base URL: `https://api.agentmail.to` - URL: `https://api.agentmail.to/v0/api-keys/{api_key_id}` - Auth: HTTP bearer Returns one credential of any family. Public keys also resolve by `client_id`. Poll a sign-in key until `status` is `active`. ## Path parameters - `api_key_id` string, required: ID of api key. ## Response `200` Response with status 200 - union: One credential of any family. `type` is `bearer` or `public_key`. A public key carrying `status` is a sign-in key; one without it is a registered signing key. - ApiKeysBearerApiKey: An API key presented as a bearer token in the `Authorization` header. - `type` 'bearer', required - `api_key_id` string, required: ID of api key. - `prefix` string, required: Prefix of api key. - `name` string, required: Name of api key. - `pod_id` string: Pod ID the api key is scoped to. If set, the key can only access resources within this pod. - `inbox_id` string: Inbox ID the api key is scoped to. If set, the key can only access resources within this inbox. - `used_at` string, date-time: Time at which api key was last used. - `permissions` ApiKeysApiKeyPermissions: Granular permissions for the API key. When ommitted all permissions are granted. Otherwise, only permissions set to true are granted. - `inbox_read` boolean: Read inbox details. - `inbox_create` boolean: Create new inboxes. - `inbox_update` boolean: Update inbox settings. - `inbox_delete` boolean: Delete inboxes. - `message_read` boolean: Read messages. Also required to read threads. - `message_reply` boolean: Reply and reply-all when the request is signed with a registered public key. Bearer keys reply with `message_send`. - `message_send` boolean: Send messages. - `message_update` boolean: Update message labels. Also required to update threads. - `message_delete` boolean: Delete messages. Also required to delete threads. - `agent_armor_release` boolean: Release mail Agent Armor holds for review. Opt-in: no key has it unless it was granted explicitly, even one without a `permissions` object. See [Permissions](/permissions#agent-armor). - `label_spam_read` boolean: Access messages labeled spam. - `label_blocked_read` boolean: Access messages labeled blocked. - `label_unauthenticated_read` boolean: Access messages labeled unauthenticated. - `label_trash_read` boolean: Access messages labeled trash. - `draft_read` boolean: Read drafts. - `draft_create` boolean: Create drafts. - `draft_update` boolean: Update drafts. - `draft_delete` boolean: Delete drafts. - `draft_send` boolean: Send drafts. - `webhook_read` boolean: Read webhook configurations. - `webhook_create` boolean: Create webhooks. - `webhook_update` boolean: Update webhooks. - `webhook_delete` boolean: Delete webhooks. - `domain_read` boolean: Read domain details. - `domain_create` boolean: Create domains. - `domain_update` boolean: Update domains. - `domain_delete` boolean: Delete domains. - `list_entry_read` boolean: Read list entries. - `list_entry_create` boolean: Create list entries. - `list_entry_delete` boolean: Delete list entries. - `metrics_read` boolean: Read metrics. - `api_key_read` boolean: Read API keys. - `api_key_create` boolean: Create API keys. - `api_key_update` boolean: Update API keys. - `api_key_delete` boolean: Delete API keys. - `app_connect` boolean: Sign in to apps as an inbox: connect an app, authorize an inbox, and mint the sign-in keys. Omitted on a new bearer key means false, whatever else the key holds. - `app_share_owner` boolean: Share the organization owner's name and email with apps at sign-in. One permission for both values. - `account_update` boolean: Update accounts: disable or re-enable an inbox's sign-in at an app. Reading accounts needs only `inbox_read`. - `pod_read` boolean: Read pods. - `pod_create` boolean: Create pods. - `pod_update` boolean: Update pods. - `pod_delete` boolean: Delete pods. - `calendar_read` boolean: Read inbox calendar settings. - `calendar_update` boolean: Update inbox calendar settings. - `calendar_event_read` boolean: Read calendar events, and receive `calendar.event.*` webhook and WebSocket events. - `calendar_event_create` boolean: Create calendar events. - `calendar_event_update` boolean: Update calendar events and respond to invitations. - `calendar_event_delete` boolean: Delete calendar events. - `file_read` boolean: Reserved; not released yet. - `file_create` boolean: Reserved; not released yet. - `file_update` boolean: Reserved; not released yet. - `file_delete` boolean: Reserved; not released yet. - `created_at` string, date-time, required: Time at which api key was created. - `updated_at` string, date-time, required: Time at which api key was last updated. - `expires_at` string, date-time: Time at which api key expires. Omitted when it does not expire. - ApiKeysPublicKeyCredential: An AgentID sign-in credential, scoped like a bearer key; `api_key_id` is the JWS `kid`. A sign-in key carries `status`, gains `public_key` once the client has proved it, expires 30 days after activation, and carries exactly `app_connect` and `app_share_owner`, snapshotted from the bearer key that created it and enforced from the key itself. - `type` 'public_key', required - `api_key_id` string, required: ID of api key. - `client_id` string: Caller-chosen alias for a public key, unique within the organization and reusable after deletion. Accepted in place of `api_key_id` on get, update, and delete. Registration is idempotent on it: the same alias returns the existing key, a conflicting one returns `409`. URL-safe; no slash or `@`. - `name` string, required: Name of api key. - `public_key` ApiKeysPublicKeyMaterial: Registered public key material and its server-computed RFC 7638 thumbprint. - `jwk` ApiKeysPublicJwk, required: A public P-256 JWK. The object accepts exactly `kty`, `crv`, `x`, and `y`. Private key material such as `d`, embedded key IDs, and all other members are rejected. The server also rejects coordinates that are not a point on P-256. - `kty` 'EC', required - `crv` 'P-256', required - `x` string, required: A 32-byte P-256 coordinate encoded as unpadded base64url. - `y` string, required: A 32-byte P-256 coordinate encoded as unpadded base64url. - `fingerprint` string, required: RFC 7638 SHA-256 JWK thumbprint encoded as unpadded base64url. - `pod_id` string: Pod ID the api key is scoped to. If set, the key can only access resources within this pod. - `inbox_id` string: Inbox ID the api key is scoped to. If set, the key can only access resources within this inbox. - `status` 'pending' | 'active': Lifecycle of a sign-in key: `pending` until the client finishes creating it on the AgentID page, `active` once it can sign in as the inbox. Absent on a registered key. - `used_at` string, date-time: Time at which api key was last used. - `permissions` ApiKeysApiKeyPermissions, required: Granular permissions for the API key. When ommitted all permissions are granted. Otherwise, only permissions set to true are granted. - `inbox_read` boolean: Read inbox details. - `inbox_create` boolean: Create new inboxes. - `inbox_update` boolean: Update inbox settings. - `inbox_delete` boolean: Delete inboxes. - `message_read` boolean: Read messages. Also required to read threads. - `message_reply` boolean: Reply and reply-all when the request is signed with a registered public key. Bearer keys reply with `message_send`. - `message_send` boolean: Send messages. - `message_update` boolean: Update message labels. Also required to update threads. - `message_delete` boolean: Delete messages. Also required to delete threads. - `agent_armor_release` boolean: Release mail Agent Armor holds for review. Opt-in: no key has it unless it was granted explicitly, even one without a `permissions` object. See [Permissions](/permissions#agent-armor). - `label_spam_read` boolean: Access messages labeled spam. - `label_blocked_read` boolean: Access messages labeled blocked. - `label_unauthenticated_read` boolean: Access messages labeled unauthenticated. - `label_trash_read` boolean: Access messages labeled trash. - `draft_read` boolean: Read drafts. - `draft_create` boolean: Create drafts. - `draft_update` boolean: Update drafts. - `draft_delete` boolean: Delete drafts. - `draft_send` boolean: Send drafts. - `webhook_read` boolean: Read webhook configurations. - `webhook_create` boolean: Create webhooks. - `webhook_update` boolean: Update webhooks. - `webhook_delete` boolean: Delete webhooks. - `domain_read` boolean: Read domain details. - `domain_create` boolean: Create domains. - `domain_update` boolean: Update domains. - `domain_delete` boolean: Delete domains. - `list_entry_read` boolean: Read list entries. - `list_entry_create` boolean: Create list entries. - `list_entry_delete` boolean: Delete list entries. - `metrics_read` boolean: Read metrics. - `api_key_read` boolean: Read API keys. - `api_key_create` boolean: Create API keys. - `api_key_update` boolean: Update API keys. - `api_key_delete` boolean: Delete API keys. - `app_connect` boolean: Sign in to apps as an inbox: connect an app, authorize an inbox, and mint the sign-in keys. Omitted on a new bearer key means false, whatever else the key holds. - `app_share_owner` boolean: Share the organization owner's name and email with apps at sign-in. One permission for both values. - `account_update` boolean: Update accounts: disable or re-enable an inbox's sign-in at an app. Reading accounts needs only `inbox_read`. - `pod_read` boolean: Read pods. - `pod_create` boolean: Create pods. - `pod_update` boolean: Update pods. - `pod_delete` boolean: Delete pods. - `calendar_read` boolean: Read inbox calendar settings. - `calendar_update` boolean: Update inbox calendar settings. - `calendar_event_read` boolean: Read calendar events, and receive `calendar.event.*` webhook and WebSocket events. - `calendar_event_create` boolean: Create calendar events. - `calendar_event_update` boolean: Update calendar events and respond to invitations. - `calendar_event_delete` boolean: Delete calendar events. - `file_read` boolean: Reserved; not released yet. - `file_create` boolean: Reserved; not released yet. - `file_update` boolean: Reserved; not released yet. - `file_delete` boolean: Reserved; not released yet. - `created_by` ApiKeysApiKeyCreator, required: The bearer API key that created the credential. Provenance only; the credential outlives it. - `api_key_id` string, required: ID of api key. - `created_at` string, date-time, required: Time at which api key was created. - `updated_at` string, date-time, required: Time at which api key was last updated. - `expires_at` string, date-time: Time at which api key expires. Omitted when it does not expire. ## Other responses - `404`: Error response with status 404 ## Changes - **2026-10-16** `3f5c7830c952`: 1 info - endpoint added [Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/api-keys/:api_key_id/get.md) --- [API](https://skmtc.dev/agentmail-to/apis/api.md) - [All operations](https://skmtc.dev/agentmail-to/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentmail-to/apis/api/revisions/a9792efe7bdf?raw)