---
title: "POST /api-keys"
method: POST
path: "/api-keys"
---

# POST /api-keys

`POST /api-keys`

## Request body

- object
  - `purpose` string, required — The API key's purpose, which restricts how it can be used.
  - `projectId` string — An optional project to restrict the API key to.
  - `name` string — An optional name for the API key.
  - `expiresAt` number — The API key's expiration, expressed as a UNIX timestamp in milliseconds.
  - `aiGatewayQuota` object — Optional AI Gateway quota configuration for the API key.
    - `limitAmount` number, required — The quota limit amount.
    - `includeByokInQuota` boolean — Whether to include BYOK (Bring Your Own Key) usage in the quota.
    - `refreshPeriod` 'daily' | 'weekly' | 'monthly' | 'none' — How often the quota refreshes.
    - `alertThresholds` number[] — Spend percentages (a subset of [50, 75, 100]) at which to send a spend alert.
  - `metadata` object — Optional generic metadata for the API key. The accepted shape depends on the key's `purpose` and is validated on creation; for `ai-gateway` keys this accepts `environment`.

## Response `200`

Successfully created an API key.

- object
  - `apiKeyString` string, required — The API key's actual value. This value is only provided in this response, and can never be retrieved again in the future. Be sure to save it somewhere safe!
  - `apiKey` APIKey, required — Information about the newly created API key.
    - `id` string, required — The unique identifier of the API key.
    - `name` string, required — The human-readable name of the API key.
    - `partialKey` string, required — The last few characters of the API key string, for helping identify the API key.
    - `teamId` string, required — The ID of the team that the API key grants access to.
    - `purpose` string, required — The API key's purpose, i.e. what resources it can be used with.
    - `projectId` string, nullable, required — The ID of the project that this API key grants access to. When this is unset, the API key grants access to all projects in the team.
    - `expiresAt` number, nullable, required — Timestamp (in milliseconds) of when the API key expires.
    - `activeAt` number, required — Timestamp (in milliseconds) of when the API key was most recently used.
    - `createdAt` number, required — Timestamp (in milliseconds) of when the API key was created.
    - `createdBy` string, required — The ID of the user who created the API key.
    - `leakedAt` number, nullable, required — Timestamp (in milliseconds) of when the API key was marked as leaked.
    - `leakedUrl` string, nullable, required — URL where the API key was discovered as leaked.
    - `createdByAppId` string, nullable, required — The ID of the app that created the API key, if any
    - `quota` APIKeyQuota — AI Gateway quota associated with an API key.
      - `quotaEntityId` string, required — The unique identifier for the quota.
      - `limitAmount` number, required — The quota limit amount.
      - `currentSpend` number, required — The current amount spent against the quota.
      - `currentByokSpend` number, required — The current BYOK spend (tracked separately).
      - `includeByokInQuota` boolean, required — Whether BYOK (Bring Your Own Key) spend counts against the quota.
      - `refreshPeriod` union, required — How often the quota refreshes.
        - string
        - string
        - string
        - string
      - `active` boolean, required — Whether the quota is currently active.
      - `archived` boolean, required — Whether the quota has been archived.
      - `alertThresholds` number[] — Spend percentages (a subset of [50, 75, 100]) at which to send a spend alert. Empty or undefined disables alerts.
      - `createdAt` number, required — Timestamp (in milliseconds) of when the quota was created.
      - `updatedAt` number, required — Timestamp (in milliseconds) of when the quota was last updated.
    - `metadata` object — Generic metadata attached to the API key. The accepted shape depends on the key's `purpose` and is validated when the key is created. For `ai-gateway` keys this carries `environment` and `spendAttribution`.

## Other responses

- `400` — One of the provided values in the request body is invalid.
- `401` — The request is not authorized.
- `403` — You do not have permission to access this resource.
- `409`
- `410`
- `429`
- `500`

---

[API](https://skmtc.net/vercel/apis/api.md) · [All operations](https://skmtc.net/vercel/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vercel/api/versions/61d1ba3f6dac/schema)