openapi: 3.1.0
info:
  title: Unkey analytics keys API
  description: 'Unkey is an open-source developer platform for API key management, authentication, and rate limiting. This is an API Evangelist modeling of Unkey''s RPC-style REST API, grounded in Unkey''s own published OpenAPI. All operations use POST and are grouped into service namespaces (keys, apis, ratelimit, identities, permissions, analytics, deploy, liveness). The stable v2 API is served from https://api.unkey.com; the legacy v1 API is served from https://api.unkey.dev with /v1/* paths.


    Authentication uses HTTP Bearer authentication with a root key: `Authorization: Bearer unkey_xxxxxxxxxxx`. Most endpoints require specific permissions on the root key. Responses use a consistent envelope with a `meta.requestId`, a `data` object (or array plus `pagination` on list endpoints), and a structured `error` object on failures.'
  version: 2.0.0
  contact:
    name: Unkey
    url: https://www.unkey.com
  license:
    name: AGPL-3.0
    url: https://github.com/unkeyed/unkey/blob/main/LICENSE.md
servers:
- url: https://api.unkey.com
  description: Unkey v2 (current)
- url: https://api.unkey.dev
  description: Unkey v1 (legacy)
security:
- rootKey: []
tags:
- name: keys
  description: API key management operations.
paths:
  /v2/keys.createKey:
    post:
      operationId: keys.createKey
      tags:
      - keys
      summary: Create a key
      description: Creates a new API key in a given API (namespace). Supports name, prefix, byteLength, externalId (identity link), meta, expiration, remaining usage credits, refill, ratelimits, permissions, and roles. Returns the plaintext key once and its keyId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/keys.verifyKey:
    post:
      operationId: keys.verifyKey
      tags:
      - keys
      summary: Verify a key
      description: Verifies an API key on the request hot path. Checks validity, expiration, remaining credits, ratelimits, permissions, and roles, and returns the key's metadata plus any linked identity. This is the endpoint API providers call on every incoming request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/keys.getKey:
    post:
      operationId: keys.getKey
      tags:
      - keys
      summary: Get a key
      description: Retrieves metadata about a single key by its keyId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/keys.updateKey:
    post:
      operationId: keys.updateKey
      tags:
      - keys
      summary: Update a key
      description: Updates a key's mutable attributes - name, meta, expiration, enabled state, external identity, ratelimits, remaining credits, permissions, and roles.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/keys.deleteKey:
    post:
      operationId: keys.deleteKey
      tags:
      - keys
      summary: Delete a key
      description: Permanently deletes (or soft-deletes) a key so it can no longer be verified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/keys.rerollKey:
    post:
      operationId: keys.rerollKey
      tags:
      - keys
      summary: Reroll a key
      description: Rotates a key by creating a new secret while preserving the key's configuration and identity, optionally keeping the old key valid until an expiration for a smooth migration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/keys.updateCredits:
    post:
      operationId: keys.updateCredits
      tags:
      - keys
      summary: Update key credits
      description: Sets, increments, or decrements the remaining usage credits on a key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/keys.whoami:
    post:
      operationId: keys.whoami
      tags:
      - keys
      summary: Who am I
      description: Resolves a plaintext key to its keyId and metadata without a full verification.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/keys.migrateKeys:
    post:
      operationId: keys.migrateKeys
      tags:
      - keys
      summary: Migrate keys
      description: Bulk-imports existing keys (by hash) from another system into an Unkey namespace, preserving prefixes and metadata so customers keep their current keys.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/keys.addPermissions:
    post:
      operationId: keys.addPermissions
      tags:
      - keys
      summary: Add permissions to a key
      description: Attaches one or more permissions to a key, creating them if requested.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/keys.removePermissions:
    post:
      operationId: keys.removePermissions
      tags:
      - keys
      summary: Remove permissions from a key
      description: Detaches one or more permissions from a key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/keys.setPermissions:
    post:
      operationId: keys.setPermissions
      tags:
      - keys
      summary: Set key permissions
      description: Replaces the full set of permissions on a key with the provided list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/keys.addRoles:
    post:
      operationId: keys.addRoles
      tags:
      - keys
      summary: Add roles to a key
      description: Attaches one or more roles to a key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/keys.removeRoles:
    post:
      operationId: keys.removeRoles
      tags:
      - keys
      summary: Remove roles from a key
      description: Detaches one or more roles from a key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/keys.setRoles:
    post:
      operationId: keys.setRoles
      tags:
      - keys
      summary: Set key roles
      description: Replaces the full set of roles on a key with the provided list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Forbidden:
      description: The root key lacks the permission required for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: Missing or invalid root key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Success:
      description: Successful response using the standard Unkey envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessEnvelope'
    BadRequest:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    ErrorEnvelope:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          type: object
          properties:
            title:
              type: string
              description: Human-readable error summary.
            detail:
              type: string
              description: Specific description of what went wrong.
            status:
              type: integer
              description: HTTP status code.
            type:
              type: string
              format: uri
              description: Link to error documentation.
            errors:
              type: array
              description: Array of validation errors (for 400 responses).
              items:
                type: object
                additionalProperties: true
    GenericRequest:
      type: object
      description: Request body for an RPC-style operation. The concrete fields depend on the operation (for example keyId, apiId, key, namespace, identifier, externalId, permissions, roles). See the Unkey API reference for the per-operation schema.
      additionalProperties: true
    SuccessEnvelope:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: object
          additionalProperties: true
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique identifier for this request, useful for support and tracing.
  securitySchemes:
    rootKey:
      type: http
      scheme: bearer
      description: 'HTTP Bearer authentication with an Unkey root key, passed as `Authorization: Bearer unkey_xxxxxxxxxxx`. Most endpoints require specific permissions on the root key.'