AgentMail API Keys API

The api-keys API from AgentMail — 2 operation(s) for api-keys.

GitHub OpenAPI
Business capability
Developer Identity & Credential Management BC-4270.40

Operations 5

GET /v0/api-keys List API Keys #
POST /v0/api-keys Create API Key #
GET /v0/api-keys/{api_key_id} Get API Key #
PATCH /v0/api-keys/{api_key_id} Update API Key #
DELETE /v0/api-keys/{api_key_id} Delete API Key #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/agentmail:agentmail-api-keys-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

agentmail-api-keys-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Reference API Keys API
  version: 1.0.0
servers:
- url: https://api.agentmail.to
  description: prod
- url: https://x402.api.agentmail.to
  description: prod-x402
- url: https://mpp.api.agentmail.to
  description: prod-mpp
- url: https://api.agentmail.eu
  description: eu-prod
tags:
- name: API Keys
paths:
  /v0/api-keys:
    get:
      operationId: apiKeys_list
      summary: List API Keys
      description: 'Lists every credential, newest first. Filter one family with `type`.

        Page to token exhaustion: a page can be empty and still carry a

        `next_page_token`.


        **CLI:**

        ```bash

        agentmail api-keys list

        ```'
      tags:
      - API Keys
      parameters:
      - name: type
        in: query
        description: Restrict the list to one credential family. Omit for every family.
        required: false
        schema:
          $ref: '#/components/schemas/apiKeys_ApiKeyType'
      - name: limit
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Limit'
      - name: page_token
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PageToken'
      - name: ascending
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Ascending'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiKeys_ListApiKeysResponse'
      security:
      - Bearer: []
    post:
      operationId: apiKeys_create
      summary: Create API Key
      description: 'Creates a bearer key, or registers a public key when the body carries

        `public_key`. The route selects the scope. Bearer secrets are returned once.


        **CLI:**

        ```bash

        agentmail api-keys create --name "My Key"

        ```'
      tags:
      - API Keys
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiKeys_CreateApiKeyResult'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '409':
          description: Error response with status 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apiKeys_CreateApiKeyRequest'
      security:
      - Bearer: []
  /v0/api-keys/{api_key_id}:
    get:
      operationId: apiKeys_get
      summary: Get API Key
      description: 'Returns one credential of any family. Public keys also resolve by

        `client_id`. Poll a sign-in key until `status` is `active`.'
      tags:
      - API Keys
      parameters:
      - name: api_key_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/apiKeys_ApiKeyId'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiKeys_ApiKey'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
    patch:
      operationId: apiKeys_update
      summary: Update API Key
      description: 'Renames a credential or changes its permissions. Public keys also resolve

        by `client_id`; a sign-in key accepts only `app_connect` and

        `app_share_owner`.'
      tags:
      - API Keys
      parameters:
      - name: api_key_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/apiKeys_ApiKeyId'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiKeys_ApiKey'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apiKeys_UpdateApiKeyRequest'
      security:
      - Bearer: []
    delete:
      operationId: apiKeys_delete
      summary: Delete API Key
      description: 'Deletes one credential of any family. A pending sign-in key is

        cancelled; an active one is revoked. Public keys also resolve by `client_id`.


        **CLI:**

        ```bash

        agentmail api-keys delete --api-key-id

        ```'
      tags:
      - API Keys
      parameters:
      - name: api_key_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/apiKeys_ApiKeyId'
      responses:
        '200':
          description: Successful response
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
components:
  schemas:
    apiKeys_InboxScopeId:
      type: string
      description: Inbox ID the api key is scoped to. If set, the key can only access resources within this inbox.
      title: InboxScopeId
    ErrorCode:
      type: string
      description: Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
      title: ErrorCode
    apiKeys_PublicJwkCoordinate:
      type: string
      pattern: ^[A-Za-z0-9_-]{43}$
      minLength: 43
      maxLength: 43
      description: A 32-byte P-256 coordinate encoded as unpadded base64url.
      title: PublicJwkCoordinate
    Count:
      type: integer
      description: Number of items returned.
      title: Count
    apiKeys_ApiKeyCreator:
      type: object
      properties:
        api_key_id:
          $ref: '#/components/schemas/apiKeys_ApiKeyId'
      required:
      - api_key_id
      description: The bearer API key that created the credential. Provenance only; the credential outlives it.
      title: ApiKeyCreator
    apiKeys_PodScopeId:
      type: string
      description: Pod ID the api key is scoped to. If set, the key can only access resources within this pod.
      title: PodScopeId
    ValidationErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ErrorName'
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          $ref: '#/components/schemas/ErrorMessage'
        errors:
          description: Validation errors. Each entry has a path and a message identifying the invalid field.
        fix:
          $ref: '#/components/schemas/ErrorFix'
        docs:
          $ref: '#/components/schemas/ErrorDocs'
      required:
      - name
      - errors
      title: ValidationErrorResponse
    apiKeys_ListApiKeysResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/Count'
        next_page_token:
          $ref: '#/components/schemas/PageToken'
        api_keys:
          type: array
          items:
            $ref: '#/components/schemas/apiKeys_ApiKey'
          description: 'Every credential family, ordered by `created_at`. `type` restricts

            to one family.'
      required:
      - count
      - api_keys
      title: ListApiKeysResponse
    apiKeys_ExpiresAt:
      type: string
      format: date-time
      description: Time at which api key expires. Omitted when it does not expire.
      title: ExpiresAt
    ErrorDocs:
      type: string
      description: Link to the error reference entry for this code.
      title: ErrorDocs
    apiKeys_ApiKey:
      oneOf:
      - $ref: '#/components/schemas/apiKeys_BearerApiKey'
      - $ref: '#/components/schemas/apiKeys_PublicKeyCredential'
      description: '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.'
      title: ApiKey
    apiKeys_CreatePublicKeyRequest:
      type: object
      properties:
        public_key:
          $ref: '#/components/schemas/apiKeys_PublicJwk'
        client_id:
          $ref: '#/components/schemas/apiKeys_PublicKeyClientId'
        name:
          $ref: '#/components/schemas/apiKeys_Name'
        permissions:
          $ref: '#/components/schemas/apiKeys_ApiKeyPermissions'
        expires_at:
          $ref: '#/components/schemas/apiKeys_ExpiresAt'
      required:
      - public_key
      description: 'Registers a public P-256 JWK at the route''s scope. `type` and

        `api_key_id` are server-owned. `name` defaults to

        `AgentID key {first eight fingerprint characters}`; `permissions`

        defaults to the registering key''s, and only grants it holds may be

        true; `expires_at` defaults to the registering key''s expiry and is

        independent of that key afterward.'
      title: CreatePublicKeyRequest
    apiKeys_PublicKeyMaterial:
      type: object
      properties:
        jwk:
          $ref: '#/components/schemas/apiKeys_PublicJwk'
        fingerprint:
          type: string
          pattern: ^[A-Za-z0-9_-]{43}$
          minLength: 43
          maxLength: 43
          description: RFC 7638 SHA-256 JWK thumbprint encoded as unpadded base64url.
      required:
      - jwk
      - fingerprint
      description: Registered public key material and its server-computed RFC 7638 thumbprint.
      title: PublicKeyMaterial
    apiKeys_Prefix:
      type: string
      description: Prefix of api key.
      title: Prefix
    apiKeys_UpdateApiKeyRequest:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/apiKeys_Name'
        permissions:
          $ref: '#/components/schemas/apiKeys_ApiKeyPermissions'
      description: 'Rename a credential or change its permissions. Key material, type,

        scope, and expiry are immutable.'
      title: UpdateApiKeyRequest
    apiKeys_ApiKeyType:
      type: string
      enum:
      - bearer
      - public_key
      title: ApiKeyType
    apiKeys_ApiKeyId:
      type: string
      description: ID of api key.
      title: ApiKeyId
    apiKeys_PublicJwk:
      type: object
      properties:
        kty:
          type: string
          enum:
          - EC
        crv:
          type: string
          enum:
          - P-256
        x:
          $ref: '#/components/schemas/apiKeys_PublicJwkCoordinate'
        y:
          $ref: '#/components/schemas/apiKeys_PublicJwkCoordinate'
      required:
      - kty
      - crv
      - x
      - y
      description: '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.'
      title: PublicJwk
    apiKeys_CreateApiKeyRequest:
      oneOf:
      - $ref: '#/components/schemas/apiKeys_CreateBearerApiKeyRequest'
      - $ref: '#/components/schemas/apiKeys_CreatePublicKeyRequest'
      description: 'A body with `public_key` registers a public-key credential; any other

        body mints a bearer key.'
      title: CreateApiKeyRequest
    ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    apiKeys_ApiKeyPermissions:
      type: object
      properties:
        inbox_read:
          type: boolean
          description: Read inbox details.
        inbox_create:
          type: boolean
          description: Create new inboxes.
        inbox_update:
          type: boolean
          description: Update inbox settings.
        inbox_delete:
          type: boolean
          description: Delete inboxes.
        message_read:
          type: boolean
          description: Read messages. Also required to read threads.
        message_reply:
          type: boolean
          description: Reply and reply-all when the request is signed with a registered public key. Bearer keys reply with `message_send`.
        message_send:
          type: boolean
          description: Send messages.
        message_update:
          type: boolean
          description: Update message labels. Also required to update threads.
        message_delete:
          type: boolean
          description: Delete messages. Also required to delete threads.
        agent_armor_release:
          type: boolean
          description: '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:
          type: boolean
          description: Access messages labeled spam.
        label_blocked_read:
          type: boolean
          description: Access messages labeled blocked.
        label_unauthenticated_read:
          type: boolean
          description: Access messages labeled unauthenticated.
        label_trash_read:
          type: boolean
          description: Access messages labeled trash.
        draft_read:
          type: boolean
          description: Read drafts.
        draft_create:
          type: boolean
          description: Create drafts.
        draft_update:
          type: boolean
          description: Update drafts.
        draft_delete:
          type: boolean
          description: Delete drafts.
        draft_send:
          type: boolean
          description: Send drafts.
        webhook_read:
          type: boolean
          description: Read webhook configurations.
        webhook_create:
          type: boolean
          description: Create webhooks.
        webhook_update:
          type: boolean
          description: Update webhooks.
        webhook_delete:
          type: boolean
          description: Delete webhooks.
        domain_read:
          type: boolean
          description: Read domain details.
        domain_create:
          type: boolean
          description: Create domains.
        domain_update:
          type: boolean
          description: Update domains.
        domain_delete:
          type: boolean
          description: Delete domains.
        list_entry_read:
          type: boolean
          description: Read list entries.
        list_entry_create:
          type: boolean
          description: Create list entries.
        list_entry_delete:
          type: boolean
          description: Delete list entries.
        metrics_read:
          type: boolean
          description: Read metrics.
        api_key_read:
          type: boolean
          description: Read API keys.
        api_key_create:
          type: boolean
          description: Create API keys.
        api_key_update:
          type: boolean
          description: Update API keys.
        api_key_delete:
          type: boolean
          description: Delete API keys.
        app_connect:
          type: boolean
          description: '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:
          type: boolean
          description: 'Share the organization owner''s name and email with apps at sign-in. One permission

            for both values.'
        account_update:
          type: boolean
          description: 'Update accounts: disable or re-enable an inbox''s sign-in at an app. Reading accounts

            needs only `inbox_read`.'
        pod_read:
          type: boolean
          description: Read pods.
        pod_create:
          type: boolean
          description: Create pods.
        pod_update:
          type: boolean
          description: Update pods.
        pod_delete:
          type: boolean
          description: Delete pods.
        calendar_read:
          type: boolean
          description: Read inbox calendar settings.
        calendar_update:
          type: boolean
          description: Update inbox calendar settings.
        calendar_event_read:
          type: boolean
          description: Read calendar events, and receive `calendar.event.*` webhook and WebSocket events.
        calendar_event_create:
          type: boolean
          description: Create calendar events.
        calendar_event_update:
          type: boolean
          description: Update calendar events and respond to invitations.
        calendar_event_delete:
          type: boolean
          description: Delete calendar events.
        file_read:
          type: boolean
          description: Reserved; not released yet.
        file_create:
          type: boolean
          description: Reserved; not released yet.
        file_update:
          type: boolean
          description: Reserved; not released yet.
        file_delete:
          type: boolean
          description: Reserved; not released yet.
      description: Granular permissions for the API key. When ommitted all permissions are granted. Otherwise, only permissions set to true are granted.
      title: ApiKeyPermissions
    apiKeys_Name:
      type: string
      description: Name of api key.
      title: Name
    apiKeys_CreateBearerApiKeyRequest:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/apiKeys_Name'
        permissions:
          $ref: '#/components/schemas/apiKeys_ApiKeyPermissions'
        expires_at:
          $ref: '#/components/schemas/apiKeys_ExpiresAt'
      description: '`expires_at` must be in the future and is immutable once the key exists.

        Omitted, the new key inherits the authenticating key''s expiry, and never

        expires only when that key never does. A key cannot create one that

        outlives it: an `expires_at` later than the authenticating key''s own

        returns `403`.'
      title: CreateBearerApiKeyRequest
    ErrorFix:
      type: string
      description: The concrete next action that resolves the error.
      title: ErrorFix
    apiKeys_UsedAt:
      type: string
      format: date-time
      description: Time at which api key was last used.
      title: UsedAt
    Limit:
      type: integer
      description: Limit of number of items returned.
      title: Limit
    apiKeys_BearerApiKey:
      type: object
      properties:
        type:
          type: string
          enum:
          - bearer
        api_key_id:
          $ref: '#/components/schemas/apiKeys_ApiKeyId'
        prefix:
          $ref: '#/components/schemas/apiKeys_Prefix'
        name:
          $ref: '#/components/schemas/apiKeys_Name'
        pod_id:
          $ref: '#/components/schemas/apiKeys_PodScopeId'
        inbox_id:
          $ref: '#/components/schemas/apiKeys_InboxScopeId'
        used_at:
          $ref: '#/components/schemas/apiKeys_UsedAt'
        permissions:
          $ref: '#/components/schemas/apiKeys_ApiKeyPermissions'
        created_at:
          $ref: '#/components/schemas/apiKeys_CreatedAt'
        updated_at:
          $ref: '#/components/schemas/apiKeys_UpdatedAt'
        expires_at:
          $ref: '#/components/schemas/apiKeys_ExpiresAt'
      required:
      - type
      - api_key_id
      - prefix
      - name
      - created_at
      - updated_at
      description: An API key presented as a bearer token in the `Authorization` header.
      title: BearerApiKey
    apiKeys_UpdatedAt:
      type: string
      format: date-time
      description: Time at which api key was last updated.
      title: UpdatedAt
    apiKeys_PublicKeyCredential:
      type: object
      properties:
        type:
          type: string
          enum:
          - public_key
        api_key_id:
          $ref: '#/components/schemas/apiKeys_ApiKeyId'
        client_id:
          $ref: '#/components/schemas/apiKeys_PublicKeyClientId'
        name:
          $ref: '#/components/schemas/apiKeys_Name'
        public_key:
          $ref: '#/components/schemas/apiKeys_PublicKeyMaterial'
        pod_id:
          $ref: '#/components/schemas/apiKeys_PodScopeId'
        inbox_id:
          $ref: '#/components/schemas/apiKeys_InboxScopeId'
        status:
          $ref: '#/components/schemas/apiKeys_PublicKeyStatus'
        used_at:
          $ref: '#/components/schemas/apiKeys_UsedAt'
        permissions:
          $ref: '#/components/schemas/apiKeys_ApiKeyPermissions'
        created_by:
          $ref: '#/components/schemas/apiKeys_ApiKeyCreator'
        created_at:
          $ref: '#/components/schemas/apiKeys_CreatedAt'
        updated_at:
          $ref: '#/components/schemas/apiKeys_UpdatedAt'
        expires_at:
          $ref: '#/components/schemas/apiKeys_ExpiresAt'
      required:
      - type
      - api_key_id
      - name
      - permissions
      - created_by
      - created_at
      - updated_at
      description: '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.'
      title: PublicKeyCredential
    apiKeys_PublicKeyStatus:
      type: string
      enum:
      - pending
      - active
      description: '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.'
      title: PublicKeyStatus
    ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    Ascending:
      type: boolean
      description: Sort in ascending temporal order.
      title: Ascending
    apiKeys_PublicKeyClientId:
      type: string
      description: '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 `@`.'
      title: PublicKeyClientId
    PageToken:
      type: string
      description: Page token for pagination.
      title: PageToken
    apiKeys_CreateApiKeyResponse:
      type: object
      properties:
        api_key_id:
          $ref: '#/components/schemas/apiKeys_ApiKeyId'
        api_key:
          type: string
          description: API key.
        prefix:
          $ref: '#/components/schemas/apiKeys_Prefix'
        name:
          $ref: '#/components/schemas/apiKeys_Name'
        pod_id:
          $ref: '#/components/schemas/apiKeys_PodScopeId'
        inbox_id:
          $ref: '#/components/schemas/apiKeys_InboxScopeId'
        permissions:
          $ref: '#/components/schemas/apiKeys_ApiKeyPermissions'
        created_at:
          $ref: '#/components/schemas/apiKeys_CreatedAt'
        expires_at:
          $ref: '#/components/schemas/apiKeys_ExpiresAt'
      required:
      - api_key_id
      - api_key
      - prefix
      - name
      - created_at
      title: CreateApiKeyResponse
    apiKeys_CreatedAt:
      type: string
      format: date-time
      description: Time at which api key was created.
      title: CreatedAt
    ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ErrorName'
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          $ref: '#/components/schemas/ErrorMessage'
        fix:
          $ref: '#/components/schemas/ErrorFix'
        docs:
          $ref: '#/components/schemas/ErrorDocs'
      required:
      - name
      - message
      title: ErrorResponse
    apiKeys_CreateApiKeyResult:
      oneOf:
      - $ref: '#/components/schemas/apiKeys_CreateApiKeyResponse'
      - $ref: '#/components/schemas/apiKeys_PublicKeyCredential'
      description: The secret-bearing bearer key, or the registered public key without any secret.
      title: CreateApiKeyResult
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
x-provenance:
  method: harvested
  publisher: AgentMail
  source: https://docs.agentmail.to/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)