---
title: "Create an issuer"
method: POST
path: "/v1/kms/issuers"
tags: ["kms"]
---

# Create an issuer

`POST /v1/kms/issuers`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v1/kms/issuers`
- Auth: HTTP bearer

Create a new KMS issuer for the authenticated team, or for the team or organization identified by a Connect policy token. An issuer owns the asymmetric signing keys used to sign tokens and messages.

## Query parameters

- `teamId` string
- `slug` string

## Request body

- object
  - `name` string, required: The name of the issuer.
  - `algorithm` 'RS256' | 'RS384' | 'RS512' | 'PS256' | 'PS384' | 'PS512' | 'ES256' | 'ES384' | 'ES512': The signing algorithm to use for the issuer.
  - `claimsSchema` object: A JSON Schema used to validate the resolved token claims when signing tokens for this issuer.
  - `policy` union
    - object
      - `kind` 'project-grant', required
      - `teamId` string, required: The team ID for the project grant policy.
      - `projectId` string, required: The project ID for the project grant policy.
      - `environments` string[], required: The environments for the project grant policy. Each entry is a system environment (production, preview, development) or a custom environment ID (env_...).
      - `tokenClaims` object: The claims that KMS should include in signed JWTs for this policy.
    - object
      - `kind` 'connex-grant', required
      - `clientId` string, required: The Connex client ID for the Connex grant policy.
      - `tokenClaims` object: The claims that KMS should include in signed JWTs for this policy.
  - `importKey` string: The PEM-encoded private key to use for the issuer.
  - `importKeyId` string: The key id to use as the imported key's JWT/JWKS `kid`. Only allowed when `importKey` is provided. Not required to be unique; the addressable key id is the server-minted `keyId` returned in the response.

## Response `201`

- object
  - `algorithm` 'ES256' | 'ES384' | 'ES512' | 'PS256' | 'PS384' | 'PS512' | 'RS256' | 'RS384' | 'RS512', required
  - `claimsSchema` object
  - `createdAt` string, required
  - `discoveryLayout` 'connect' | 'kms', required
  - `id` string, required
  - `managedBy` string
  - `name` string, required
  - `origin` 'external' | 'vercel', required
  - `ownerId` string, required
  - `policies` union[], required
    - union
      - object
        - `createdAt` string, required
        - `environments` string[], required: Environments whose OIDC tokens this grant authorizes. Each entry is either a system environment slug (`production`, `preview`, `development`) or a custom environment ID (prefixed `env_`). Custom environments are matched against the token's `custom_environment_id` claim (the stable ID); system environments against its `environment` claim.
        - `kind` 'project-grant', required
        - `projectId` string, required
        - `teamId` string, required
        - `tokenClaims` object
        - `updatedAt` string, required
      - object
        - `clientId` string, required
        - `createdAt` string, required
        - `kind` 'connex-grant', required
        - `tokenClaims` object
        - `updatedAt` string, required
  - `signingKeys` object[], required
    - `activateAt` string
    - `activatedAt` string: When the key became the active signer. Present for active and revoking keys (and absent for pending keys and rows predating this field).
    - `algorithm` string, required
    - `certificatePem` string: The stored X.509 certificate (from `publicKey.x5c[0]`) in PEM form, ready to render. Present only for keys created with a stored certificate; omitted for keys created before certificates were stored.
    - `createdAt` string, required
    - `importKeyId` string: The caller-supplied key id (imported keys only), used as the JWT/JWKS `kid`. Not unique across an issuer's keys; omitted for generated keys.
    - `issuerId` string, required
    - `keyId` string, required: The server-minted, unique record identifier. Use this to address the key on the activate / certificate endpoints.
    - `publicKey` object
      - `alg` string
      - `key_ops` string[]
      - `kid` string
      - `kty` string
      - `use` string
      - `x5c` string[]: The X.509 certificate chain (RFC 7517 §4.7). Each entry is the base64 DER (not base64url) of a certificate. For keys minted with a stored certificate this holds the single self-signed cert as `[x5c]`.
      - `x5t#S256` string: The base64url SHA-256 thumbprint of the DER certificate in `x5c[0]` (RFC 7517 §4.9).
    - `publicKeyFingerprint` string, required
    - `publicKeyPem` string: The public key in SPKI PEM form, ready to render. Present whenever the key has public key material. Derived from `publicKey`; the embedded certificate members (`x5c`/`x5t#S256`) do not affect it.
    - `revokeAt` string
    - `status` 'active' | 'pending' | 'revoking', required
    - `updatedAt` string, required
  - `updatedAt` string, required

## 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.
- `404`
- `409`
- `410`

## Changes

- **2026-10-30** `70c91b09be6e`: 2 info
  - added the non-success response with the status `409`
  - added the required property `discoveryLayout` to the response with the `201` status
- **2026-09-24** `dd6a90982ed0`: 1 info
  - the response property `signingKeys/items/publicKeyFingerprint` became required for the status `201`
- **2026-09-16** `d1cd8167595b`: 1 info
  - removed the `EdDSA` enum value from the `algorithm` response property for the response status `201`
- **2026-09-07** `6f213ca96d94`: 1 breaking
  - removed the enum value `EdDSA` of the request property `algorithm`
- **2026-08-19** `6b6e0450635c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v1/kms/issuers/post.md)

---

[API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)