openapi: 3.1.0
info:
  description: "Unkey's API provides programmatic access for all resources within our platform.\n\n\n### Authentication\n\
    #\nThis API uses HTTP Bearer authentication with root keys. Most endpoints require specific permissions associated with\
    \ your root key. When making requests, include your root key in the `Authorization` header:\n```\nAuthorization: Bearer\
    \ unkey_xxxxxxxxxxx\n```\n\nAll responses follow a consistent envelope structure that separates operational metadata from\
    \ actual data. This design provides several benefits:\n- Debugging: Every response includes a unique requestId for tracing\
    \ issues\n- Consistency: Predictable response format across all endpoints\n- Extensibility: Easy to add new metadata without\
    \ breaking existing integrations\n- Error Handling: Unified error format with actionable information\n\n### Success Response\
    \ Format:\n```json\n{\n  \"meta\": {\n    \"requestId\": \"req_123456\"\n  },\n  \"data\": {\n    // Actual response data\
    \ here\n  }\n}\n```\n\nThe meta object contains operational information:\n- `requestId`: Unique identifier for this request\
    \ (essential for support)\n\nThe data object contains the actual response data specific to each endpoint.\n\n### Paginated\
    \ Response Format:\n```json\n{\n  \"meta\": {\n    \"requestId\": \"req_123456\"\n  },\n  \"data\": [\n    // Array of\
    \ results\n  ],\n  \"pagination\": {\n    \"cursor\": \"next_page_token\",\n    \"hasMore\": true\n  }\n}\n```\n\nThe\
    \ pagination object appears on list endpoints and contains:\n- `cursor`: Token for requesting the next page\n- `hasMore`:\
    \ Whether more results are available\n\n### Error Response Format:\n```json\n{\n  \"meta\": {\n    \"requestId\": \"req_2c9a0jf23l4k567\"\
    \n  },\n  \"error\": {\n    \"detail\": \"The resource you are attempting to modify is protected and cannot be changed\"\
    ,\n    \"status\": 403,\n    \"title\": \"Forbidden\",\n    \"type\": \"https://unkey.com/docs/errors/unkey/application/protected_resource\"\
    \n  }\n}\n```\n\nError responses include comprehensive diagnostic information:\n- `title`: Human-readable error summary\n\
    - `detail`: Specific description of what went wrong\n- `status`: HTTP status code\n- `type`: Link to error documentation\n\
    - `errors`: Array of validation errors (for 400 responses)\n\nThis structure ensures you always have the context needed\
    \ to debug issues and take corrective action."
  title: Unkey API
  version: 2.0.0
servers:
- url: https://api.unkey.com
tags:
- description: Analytics query operations
  name: analytics
- description: API management operations
  name: apis
- description: Deployment operations
  name: deploy
- description: Identity management operations
  name: identities
- description: API key management operations
  name: keys
- description: Health check operations
  name: liveness
- description: Permission and role management operations
  name: permissions
- description: Rate limiting operations
  name: ratelimit
security:
- rootKey: []
paths:
  /v2/analytics.getVerifications:
    post:
      description: 'Execute custom SQL queries against your key verification analytics.

        For complete documentation including available tables, columns, data types, query examples, see the schema reference
        in the API documentation.

        '
      operationId: analytics.getVerifications
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2AnalyticsGetVerificationsRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2AnalyticsGetVerificationsResponseBody'
          description: Query executed successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Invalid SQL query or blocked operation
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Missing or invalid authentication
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Referenced API or identity not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityErrorResponse'
          description: Query exceeds resource limits (timeout, memory, rows scanned, or result size)
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Query quota exceeded
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Query execution failed
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableErrorResponse'
          description: Connection to the database failed
      security:
      - rootKey: []
      summary: Query Key Verification Data
      tags:
      - analytics
      x-speakeasy-name-override: getVerifications
  /v2/apis.createApi:
    post:
      description: 'Create an API namespace for organizing keys by environment, service, or product.


        Use this to separate production from development keys, isolate different services, or manage multiple products. Each
        API gets a unique identifier and dedicated infrastructure for secure key operations.


        **Important**: API names must be unique within your workspace and cannot be changed after creation.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.create_api` (to create APIs in any workspace)

        '
      operationId: apis.createApi
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2ApisCreateApiRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ApisCreateApiResponseBody'
          description: 'API namespace created successfully. The response contains the unique API ID for referencing this namespace
            in key operations.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Create API Namespace
      tags:
      - apis
      x-speakeasy-name-override: createApi
  /v2/apis.deleteApi:
    post:
      description: 'Permanently delete an API namespace and immediately invalidate all associated keys.


        Use this for cleaning up development environments, retiring deprecated services, or removing unused resources.

        All keys in the namespace are immediately marked as deleted and will fail verification with `code=NOT_FOUND`.


        **Important**: This operation is immediate and permanent. Verify you have the correct API ID before deletion.

        If delete protection is enabled, disable it first through the dashboard or API configuration.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.delete_api` (to delete any API)

        - `api.<api_id>.delete_api` (to delete a specific API)

        '
      operationId: apis.deleteApi
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2ApisDeleteApiRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ApisDeleteApiResponseBody'
          description: API namespace deleted successfully. All associated keys are immediately invalidated and will fail verification
            with `code=NOT_FOUND`.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreconditionFailedErrorResponse'
          description: Delete protection is enabled. Disable protection through the dashboard or API configuration, then retry
            the deletion.
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Delete API Namespace
      tags:
      - apis
      x-speakeasy-name-override: deleteApi
  /v2/apis.getApi:
    post:
      description: 'Retrieve basic information about an API namespace including its ID and name.


        Use this to verify an API exists before performing operations, get the human-readable name when you only have the
        API ID, or confirm access to a specific namespace. For detailed key information, use the `listKeys` endpoint instead.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.read_api` (to read any API)

        - `api.<api_id>.read_api` (to read a specific API)

        '
      operationId: apis.getApi
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2ApisGetApiRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ApisGetApiResponseBody'
          description: API information retrieved successfully. Contains the unique API ID and human-readable name.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Get API Namespace
      tags:
      - apis
      x-speakeasy-name-override: getApi
  /v2/apis.listKeys:
    post:
      description: 'Retrieve a paginated list of API keys for dashboard and administrative interfaces.


        Use this to build key management dashboards, filter keys by user with `externalId`, or retrieve key details for administrative
        purposes. Each key includes status, metadata, permissions, and usage limits.


        **Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.


        **Required Permissions**


        Your root key must have one of the following permissions for basic key listing:

        - `api.*.read_key` (to read keys from any API)

        - `api.<api_id>.read_key` (to read keys from a specific API)


        Additionally, you need read access to the API itself:

        - `api.*.read_api` or `api.<api_id>.read_api`


        Additional permission required for decrypt functionality:

        - `api.*.decrypt_key` or `api.<api_id>.decrypt_key`

        '
      operationId: apis.listKeys
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2ApisListKeysRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ApisListKeysResponseBody'
          description: 'Successfully retrieved paginated keys. Use the pagination cursor for additional results when `hasMore:
            true`.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: List API Keys
      tags:
      - apis
      x-speakeasy-name-override: listKeys
  /v2/deploy.createDeployment:
    post:
      description: '**INTERNAL** - This endpoint is internal and may change without notice.

        Not recommended for production use.


        Creates a new deployment for a project using either a pre-built Docker image or build context.


        **Authentication**: Requires a valid root key with appropriate permissions.

        '
      operationId: deploy.createDeployment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2DeployCreateDeploymentRequestBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2DeployCreateDeploymentResponseBody'
          description: Deployment created successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Create Deployment
      tags:
      - deploy
      x-speakeasy-group: internal
      x-speakeasy-name-override: createDeployment
  /v2/deploy.getDeployment:
    post:
      description: '**INTERNAL** - This endpoint is internal and may change without notice.

        Not recommended for production use.


        Retrieves deployment information including status, error messages, and steps.


        **Authentication**: Requires a valid root key with appropriate permissions.

        '
      operationId: deploy.getDeployment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2DeployGetDeploymentRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2DeployGetDeploymentResponseBody'
          description: Deployment retrieved successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Get Deployment
      tags:
      - deploy
      x-speakeasy-group: internal
      x-speakeasy-name-override: getDeployment
  /v2/identities.createIdentity:
    post:
      description: 'Create an identity to group multiple API keys under a single entity. Identities enable shared rate limits
        and metadata across all associated keys.


        Perfect for users with multiple devices, organizations with multiple API keys, or when you need unified rate limiting
        across different services.


        **Important**

        Requires `identity.*.create_identity` permission

        '
      operationId: identities.createIdentity
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: Simple identity
                value:
                  externalId: user_123
              withMetadata:
                summary: With user data
                value:
                  externalId: user_123
                  meta:
                    email: alice@example.com
                    name: Alice Smith
                    plan: premium
              withRatelimits:
                summary: With rate limits
                value:
                  externalId: user_123
                  ratelimits:
                  - duration: 60000
                    limit: 1000
                    name: requests
            schema:
              $ref: '#/components/schemas/V2IdentitiesCreateIdentityRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  summary: Successfully created identity
                  value:
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
              schema:
                $ref: '#/components/schemas/V2IdentitiesCreateIdentityResponseBody'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              examples:
                missingPermission:
                  summary: Missing required permission
                  value:
                    error:
                      detail: Your root key requires the 'identity.*.create_identity' permission to perform this operation
                      status: 403
                      title: Forbidden
                      type: forbidden
                    meta:
                      requestId: req_0uVwX4yZaAbCdEfGhIjKl
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden - Insufficient permissions (requires `identity.*.create_identity`)
        '409':
          content:
            application/json:
              examples:
                identityExists:
                  summary: Identity already exists
                  value:
                    error:
                      detail: Identity with externalId "user_abc123" already exists in this workspace.
                      status: 409
                      title: Conflict
                      type: conflict
                    meta:
                      requestId: req_2wXyZaAbCdEfGhIjKlMnOp
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
          description: Conflict - Identity with this externalId already exists
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Create Identity
      tags:
      - identities
      x-speakeasy-name-override: createIdentity
  /v2/identities.deleteIdentity:
    post:
      description: 'Permanently delete an identity. This operation cannot be undone.


        Use this for data cleanup, compliance requirements, or when removing entities from your system.


        > **Important**

        > Requires `identity.*.delete_identity` permission

        > Associated API keys remain functional but lose shared resources

        > External ID becomes available for reuse immediately

        '
      operationId: identities.deleteIdentity
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: Delete identity
                value:
                  identity: user_123
            schema:
              $ref: '#/components/schemas/V2IdentitiesDeleteIdentityRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  summary: Successful deletion
                  value:
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
              schema:
                $ref: '#/components/schemas/V2IdentitiesDeleteIdentityResponseBody'
          description: Identity successfully deleted
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              examples:
                missingPermission:
                  summary: Missing required permission
                  value:
                    error:
                      detail: Your root key requires the 'identity.*.delete_identity' permission to perform this operation
                      status: 403
                      title: Forbidden
                      type: forbidden
                    meta:
                      requestId: req_0uVwX4yZaAbCdEfGhIjKl
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden - Insufficient permissions (requires `identity.*.delete_identity`)
        '404':
          content:
            application/problem+json:
              examples:
                identityNotFound:
                  summary: Identity not found
                  value:
                    error:
                      detail: Identity with externalId "user_abc123" not found.
                      status: 404
                      title: Not Found
                      type: not_found
                    meta:
                      requestId: req_2wXyZaAbCdEfGhIjKlMnOp
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found - Identity with the specified externalId doesn't exist
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Error
      security:
      - rootKey: []
      summary: Delete Identity
      tags:
      - identities
      x-speakeasy-name-override: deleteIdentity
  /v2/identities.getIdentity:
    post:
      description: 'Retrieve an identity by external ID. Returns metadata, rate limits, and other associated data.


        Use this to check if an identity exists, view configurations, or build management dashboards.


        > **Important**

        > Requires `identity.*.read_identity` permission

        '
      operationId: identities.getIdentity
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: Get identity
                value:
                  identity: user_123
            schema:
              $ref: '#/components/schemas/V2IdentitiesGetIdentityRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  summary: Identity found
                  value:
                    data:
                      externalId: user_123
                      id: id_1234567890abcdef
                      meta:
                        email: alice@example.com
                        name: Alice Smith
                        plan: premium
                      ratelimits:
                      - duration: 60000
                        limit: 1000
                        name: requests
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
              schema:
                $ref: '#/components/schemas/V2IdentitiesGetIdentityResponseBody'
          description: Successfully retrieved the identity information
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              examples:
                missingPermission:
                  summary: Missing required permission
                  value:
                    error:
                      detail: Your root key requires the 'identity.*.read_identity' permission to perform this operation
                      status: 403
                      title: Forbidden
                      type: forbidden
                    meta:
                      requestId: req_0uVwX4yZaAbCdEfGhIjKl
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden - Insufficient permissions (requires `identity.*.read_identity`)
        '404':
          content:
            application/json:
              examples:
                identityNotFound:
                  summary: Identity not found
                  value:
                    error:
                      detail: Identity with externalId "user_abc123" not found.
                      status: 404
                      title: Not Found
                      type: not_found
                    meta:
                      requestId: req_2wXyZaAbCdEfGhIjKlMnOp
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found - Identity with the specified externalId doesn't exist
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Get Identity
      tags:
      - identities
      x-speakeasy-name-override: getIdentity
  /v2/identities.listIdentities:
    post:
      description: 'Get a paginated list of all identities in your workspace. Returns metadata and rate limit configurations.


        Perfect for building management dashboards, auditing configurations, or browsing your identities.


        > **Important**

        > Requires `identity.*.read_identity` permission

        '
      operationId: identities.listIdentities
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: List identities
                value:
                  limit: 50
              withCursor:
                summary: With pagination cursor
                value:
                  cursor: cursor_eyJrZXkiOiJrZXlfMTIzNCJ9
                  limit: 50
            schema:
              $ref: '#/components/schemas/V2IdentitiesListIdentitiesRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  summary: Identities retrieved
                  value:
                    data:
                      cursor: cursor_eyJsYXN0SWQiOiJpZF8wMlpZUjNROU5QOEpNNFg4SFdTS1BXNDNKRiJ9
                      identities:
                      - externalId: user_123
                        id: id_01H9TQP8NP8JN3X8HWSKPW43JE
                        meta:
                          name: Alice Smith
                          plan: premium
                        ratelimits:
                        - duration: 60000
                          limit: 1000
                          name: requests
                      - externalId: user_456
                        id: id_02ZYR3Q9NP8JM4X8HWSKPW43JF
                        meta:
                          name: Bob Johnson
                          plan: basic
                        ratelimits:
                        - duration: 60000
                          limit: 500
                          name: requests
                      total: 247
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
              schema:
                $ref: '#/components/schemas/V2IdentitiesListIdentitiesResponseBody'
          description: Successfully retrieved the list of identities
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad Request - Invalid parameters
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized - Missing or invalid authentication
        '403':
          content:
            application/json:
              examples:
                missingPermission:
                  summary: Missing required permission
                  value:
                    error:
                      detail: Your root key requires the 'identity.*.read_identity' permission to perform this operation
                      status: 403
                      title: Forbidden
                      type: forbidden
                    meta:
                      requestId: req_0uVwX4yZaAbCdEfGhIjKl
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden - Insufficient permissions (requires `identity.*.read_identity`)
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: List Identities
      tags:
      - identities
      x-speakeasy-name-override: listIdentities
      x-speakeasy-pagination:
        inputs:
        - in: requestBody
          name: cursor
          type: cursor
        outputs:
          nextCursor: $.data.cursor
        type: cursor
  /v2/identities.updateIdentity:
    post:
      description: 'Update an identity''s metadata and rate limits. Only specified fields are modified - others remain unchanged.


        Perfect for subscription changes, plan upgrades, or updating user information. Changes take effect immediately.


        > **Important**

        > Requires `identity.*.update_identity` permission

        > Rate limit changes propagate within 30 seconds

        '
      operationId: identities.updateIdentity
      requestBody:
        content:
          application/json:
            examples:
              updateMetadata:
                summary: Update metadata
                value:
                  identity: user_123
                  meta:
                    email: alice@example.com
                    name: Alice Smith
                    plan: premium
            schema:
              $ref: '#/components/schemas/V2IdentitiesUpdateIdentityRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2IdentitiesUpdateIdentityResponseBody'
          description: Identity successfully updated
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              examples:
                missingPermission:
                  summary: Missing required permission
                  value:
                    error:
                      detail: Your root key requires the 'identity.*.update_identity' permission to perform this operation
                      status: 403
                      title: Forbidden
                      type: forbidden
                    meta:
                      requestId: req_0uVwX4yZaAbCdEfGhIjKl
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden - Insufficient permissions (requires `identity.*.update_identity`)
        '404':
          content:
            application/json:
              examples:
                identityNotFound:
                  summary: Identity not found
                  value:
                    error:
                      detail: Identity with externalId "user_123" not found.
                      status: 404
                      title: Not Found
                      type: not_found
                    meta:
                      requestId: req_2wXyZaAbCdEfGhIjKlMnOp
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found - Identity with the specified ID or externalId doesn't exist
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Update Identity
      tags:
      - identities
      x-speakeasy-name-override: updateIdentity
  /v2/keys.addPermissions:
    post:
      description: 'Add permissions to a key without affecting existing permissions.


        Use this for privilege upgrades, enabling new features, or plan changes that grant additional capabilities. Permissions
        granted through roles remain unchanged.


        **Important**: Changes take effect immediately with up to 30-second edge propagation.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.update_key` (to update keys in any API)

        - `api.<api_id>.update_key` (to update keys in a specific API)


        **Side Effects**


        Invalidates the key cache for immediate effect, and makes permissions available for verification within 30 seconds
        across all regions.

        '
      operationId: keys.addPermissions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysAddPermissionsRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysAddPermissionsResponseBody'
          description: Permissions added successfully. Returns all permissions currently assigned to the key.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Add Key Permissions
      tags:
      - keys
      x-speakeasy-name-override: addPermissions
  /v2/keys.addRoles:
    post:
      description: 'Add roles to a key without affecting existing roles or permissions.


        Use this for privilege upgrades, enabling new feature sets, or subscription changes that grant additional role-based
        capabilities. Direct permissions remain unchanged.


        **Important**: Changes take effect immediately with up to 30-second edge propagation.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.update_key` (to update keys in any API)

        - `api.<api_id>.update_key` (to update keys in a specific API)


        **Side Effects**


        Invalidates the key cache for immediate effect, and makes role assignments available for verification within 30 seconds
        across all regions.

        '
      operationId: keys.addRoles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysAddRolesRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysAddRolesResponseBody'
          description: Roles added successfully. Returns all roles currently assigned to the key.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Add Key Roles
      tags:
      - keys
      x-speakeasy-name-override: addRoles
  /v2/keys.createKey:
    post:
      description: 'Create a new API key for user authentication and authorization.


        Use this endpoint when users sign up, upgrade subscription tiers, or need additional keys. Keys are cryptographically
        secure and unique to the specified API namespace.


        **Important**: The key is returned only once. Store it immediately and provide it to your user, as it cannot be retrieved
        later.


        **Common use cases:**

        - Generate keys for new user registrations

        - Create additional keys for different applications

        - Issue keys with specific permissions or limits


        **Required Permissions**


        Your root key needs one of:

        - `api.*.create_key` (create keys in any API)

        - `api.<api_id>.create_key` (create keys in specific API)

        '
      operationId: keys.createKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysCreateKeyRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysCreateKeyResponseBody'
          description: 'Successfully created a new API key. The response includes both the keyId (for reference in your system)
            and the full key string. IMPORTANT: This is the only time the complete key is available - it cannot be retrieved
            later. You must securely provide this key to your end user immediately.'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Create API Key
      tags:
      - keys
      x-speakeasy-name-override: createKey
  /v2/keys.deleteKey:
    post:
      description: 'Delete API keys permanently from user accounts or for cleanup purposes.


        Use this for user-requested key deletion, account deletion workflows, or cleaning up unused keys. Keys are immediately
        invalidated. Two modes: soft delete (default, preserves audit records) and permanent delete.


        **Important**: For temporary access control, use `updateKey` with `enabled: false` instead of deletion.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.delete_key` (to delete keys in any API)

        - `api.<api_id>.delete_key` (to delete keys in a specific API)

        '
      operationId: keys.deleteKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysDeleteKeyRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysDeleteKeyResponseBody'
          description: 'Key deleted successfully. Verification fails immediately with up to 30-second edge propagation.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Delete API Keys
      tags:
      - keys
      x-speakeasy-name-override: deleteKey
  /v2/keys.getKey:
    post:
      description: 'Retrieve detailed key information for dashboard interfaces and administrative purposes.


        Use this to build key management dashboards showing users their key details, status, permissions, and usage data.
        You can identify keys by `keyId` or the actual key string.


        **Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.


        **Required Permissions**


        Your root key must have one of the following permissions for basic key information:

        - `api.*.read_key` (to read keys from any API)

        - `api.<api_id>.read_key` (to read keys from a specific API)


        Additional permission required for decrypt functionality:

        - `api.*.decrypt_key` or `api.<api_id>.decrypt_key`

        '
      operationId: keys.getKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysGetKeyRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysGetKeyResponseBody'
          description: 'Successfully retrieved key information. When `decrypt: true`, includes plaintext key value for recoverable
            keys.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Get API Key
      tags:
      - keys
      x-speakeasy-name-override: getKey
  /v2/keys.migrateKeys:
    post:
      description: 'Returns HTTP 200 even on partial success; hashes that could not be migrated are listed under `data.failed`.


        **Required Permissions**

        Your root key must have one of the following permissions for basic key information:

        - `api.*.create_key` (to migrate keys to any API)

        - `api.<api_id>.create_key` (to migrate keys to a specific API)

        '
      operationId: keys.migrateKeys
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysMigrateKeysRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysMigrateKeysResponseBody'
          description: Successfully migrated keys.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Migrate API Key(s)
      tags:
      - keys
      x-speakeasy-name-override: migrateKeys
  /v2/keys.removePermissions:
    post:
      description: 'Remove permissions from a key without affecting existing roles or other permissions.


        Use this for privilege downgrades, removing temporary access, or plan changes that revoke specific capabilities. Permissions
        granted through roles remain unchanged.


        **Important**: Changes take effect immediately with up to 30-second edge propagation.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.update_key` (to update keys in any API)

        - `api.<api_id>.update_key` (to update keys in a specific API)


        **Side Effects**


        Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30
        seconds across all regions.

        '
      operationId: keys.removePermissions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysRemovePermissionsRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysRemovePermissionsResponseBody'
          description: Permissions removed successfully. Returns all permissions currently assigned to the key.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Remove Key Permissions
      tags:
      - keys
      x-speakeasy-name-override: removePermissions
  /v2/keys.removeRoles:
    post:
      description: 'Remove roles from a key without affecting direct permissions or other roles.


        Use this for privilege downgrades, removing temporary access, or subscription changes that revoke specific role-based
        capabilities. Direct permissions remain unchanged.


        **Important**: Changes take effect immediately with up to 30-second edge propagation.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.update_key` (to update keys in any API)

        - `api.<api_id>.update_key` (to update keys in a specific API)


        **Side Effects**


        Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds
        across all regions.

        '
      operationId: keys.removeRoles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysRemoveRolesRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysRemoveRolesResponseBody'
          description: Roles removed successfully. Returns all roles currently assigned to the key.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Remove Key Roles
      tags:
      - keys
      x-speakeasy-name-override: removeRoles
  /v2/keys.rerollKey:
    post:
      description: "Generate a new API key while preserving the configuration from an existing key.\n\nThis operation creates\
        \ a fresh key with a new token while maintaining all settings from the original key:\n- Permissions and roles\n- Custom\
        \ metadata\n- Rate limit configurations\n- Identity associations\n- Remaining credits\n- Recovery settings\n\n**Key\
        \ Generation:**\n- The system attempts to extract the prefix from the original key\n- If prefix extraction fails,\
        \ the default API prefix is used\n- Key length follows the API's default byte configuration (or 16 bytes if not specified)\n\
        \n**Original Key Handling:**\n- The original key will be revoked after the duration specified in `expiration`\n- Set\
        \ `expiration` to 0 to revoke immediately\n- This allows for graceful key rotation with an overlap period\n\nCommon\
        \ use cases include:\n- Rotating keys for security compliance\n- Issuing replacement keys for compromised credentials\n\
        - Creating backup keys with identical permissions\n\n**Important:** Analytics and usage metrics are tracked at both\
        \ the key level AND identity level. If the original key has an identity, the new key will inherit it, allowing you\
        \ to track usage across both individual keys and the overall identity.\n\n**Required Permissions**\n\n Your root key\
        \ must have:\n - `api.*.create_key` or `api.<api_id>.create_key`\n - `api.*.encrypt_key` or `api.<api_id>.encrypt_key`\
        \ (only when the original key is recoverable)\n"
      operationId: keys.rerollKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysRerollKeyRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysRerollKeyResponseBody'
          description: Key rerolled successfully.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Reroll Key
      tags:
      - keys
      x-speakeasy-name-override: rerollKey
  /v2/keys.setPermissions:
    post:
      description: 'Replace all permissions on a key with the specified set in a single atomic operation.


        Use this to synchronize with external systems, reset permissions to a known state, or apply standardized permission
        templates. Permissions granted through roles remain unchanged.


        **Important**: Changes take effect immediately with up to 30-second edge propagation.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.update_key` (to update keys in any API)

        - `api.<api_id>.update_key` (to update keys in a specific API)


        **Side Effects**


        Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30
        seconds across all regions.

        '
      operationId: keys.setPermissions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysSetPermissionsRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysSetPermissionsResponseBody'
          description: Permissions set successfully. Returns all permissions currently assigned to the key.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Set Key Permissions
      tags:
      - keys
      x-speakeasy-name-override: setPermissions
  /v2/keys.setRoles:
    post:
      description: 'Replace all roles on a key with the specified set in a single atomic operation.


        Use this to synchronize with external systems, reset roles to a known state, or apply standardized role templates.
        Direct permissions are never affected.


        **Important**: Changes take effect immediately with up to 30-second edge propagation.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.update_key` (to update keys in any API)

        - `api.<api_id>.update_key` (to update keys in a specific API)


        **Side Effects**


        Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds
        across all regions.

        '
      operationId: keys.setRoles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysSetRolesRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysSetRolesResponseBody'
          description: Roles set successfully. Returns all roles currently assigned to the key.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Set Key Roles
      tags:
      - keys
      x-speakeasy-name-override: setRoles
  /v2/keys.updateCredits:
    post:
      description: 'Update credit quotas in response to plan changes, billing cycles, or usage purchases.


        Use this for user upgrades/downgrades, monthly quota resets, credit purchases, or promotional bonuses. Supports three
        operations: set, increment, or decrement credits. Set to null for unlimited usage.


        **Important**: Setting unlimited credits automatically clears existing refill configurations.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.update_key` (to update keys in any API)

        - `api.<api_id>.update_key` (to update keys in a specific API)


        **Side Effects**


        Credit updates remove the key from cache immediately. Setting credits to unlimited automatically clears any existing
        refill settings. Changes take effect instantly but may take up to 30 seconds to propagate to all edge regions.

        '
      operationId: keys.updateCredits
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysUpdateCreditsRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysUpdateCreditsResponseBody'
          description: 'Credits updated successfully. Response includes updated remaining credits and refill settings.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Update Key Credits
      tags:
      - keys
      x-speakeasy-name-override: updateCredits
  /v2/keys.updateKey:
    post:
      description: 'Update key properties in response to plan changes, subscription updates, or account status changes.


        Use this for user upgrades/downgrades, role modifications, or administrative changes. Supports partial updates - only
        specify fields you want to change. Set fields to null to clear them.


        **Important**: Permissions and roles are replaced entirely. Use dedicated add/remove endpoints for incremental changes.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `api.*.update_key` (to update keys in any API)

        - `api.<api_id>.update_key` (to update keys in a specific API)


        **Side Effects**


        If you specify an `externalId` that doesn''t exist, a new identity will be automatically created and linked to the
        key. Permission updates will auto-create any permissions that don''t exist in your workspace. Changes take effect
        immediately but may take up to 30 seconds to propagate to all edge regions due to cache invalidation.

        '
      operationId: keys.updateKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysUpdateKeyRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  summary: Successful update
                  value:
                    data: {}
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQY
              schema:
                $ref: '#/components/schemas/V2KeysUpdateKeyResponseBody'
          description: 'Key updated successfully. Changes take effect immediately with up to 30-second edge propagation.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Update Key Settings
      tags:
      - keys
      x-speakeasy-name-override: updateKey
  /v2/keys.verifyKey:
    post:
      description: 'Verify an API key''s validity and permissions for request authentication.


        Use this endpoint on every incoming request to your protected resources. It checks key validity, permissions, rate
        limits, and usage quotas in a single call.


        **Important**: Returns HTTP 200 for all verification outcomes — check the `valid` field in response data to determine
        if the key is authorized. A 429 may be returned if the workspace exceeds its API rate limit.


        **Common use cases:**

        - Authenticate API requests before processing

        - Enforce permission-based access control

        - Track usage and apply rate limits


        **Required Permissions**


        Your root key needs one of:

        - `api.*.verify_key` (verify keys in any API)

        - `api.<api_id>.verify_key` (verify keys in specific API)


        **Note**: If your root key has no verify permissions at all, you will receive a `403 Forbidden` error. If your root
        key has verify permissions for a different API than the key you''re verifying, you will receive a `200` response with
        `code: NOT_FOUND` to avoid leaking key existence.

        '
      operationId: keys.verifyKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysVerifyKeyRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysVerifyKeyResponseBody'
          description: 'Key verification process completed. This endpoint always returns HTTP 200 regardless of whether the
            key passed or failed verification. You must check the `valid` field in the response data to determine the actual
            verification result.


            When verification succeeds, the response includes comprehensive information about the key including its current
            status, remaining credits, expiration time, associated permissions and roles, metadata, and any rate limiting
            information. This data enables your application to make informed authorization decisions and provide appropriate
            user experiences.


            When verification fails, the response indicates the specific reason through the `code` field while setting `valid`
            to false. The failure codes help you handle different scenarios appropriately, such as directing users to renew
            expired keys, upgrade for more credits, or contact support for disabled keys.


            The response also includes identity information when the key is associated with an identity, providing additional
            context about the key holder and any identity-specific rate limits or metadata that may apply to the verification.

            '
        '400':
          content:
            application/json:
              examples:
                permissionsQuerySyntaxError:
                  summary: Invalid permissions query syntax
                  value:
                    error:
                      detail: 'Syntax error in permission query: unexpected token ''AND'' at position 15. Expected permission
                        name or opening parenthesis.'
                      errors:
                      - fix: Check your query syntax. AND/OR operators must be between permissions, not at the start or end
                        location: body.permissions
                        message: unexpected token 'AND' at position 15
                      status: 400
                      title: Bad Request
                      type: https://unkey.com/docs/errors/user/bad_request/permissions_query_syntax_error
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: 'Forbidden. Returned when the root key has no verify permissions at all (neither `api.*.verify_key`
            nor `api.<api_id>.verify_key` for any API).

            '
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Verify API Key
      tags:
      - keys
      x-speakeasy-name-override: verifyKey
  /v2/keys.whoami:
    post:
      description: 'Find out what key this is.


        **Required Permissions**


        Your root key must have one of the following permissions for basic key information:

        - `api.*.read_key` (to read keys from any API)

        - `api.<api_id>.read_key` (to read keys from a specific API)


        If your rootkey lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existance
        of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your
        root key has the correct permissions.

        '
      operationId: keys.whoami
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2KeysWhoamiRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2KeysWhoamiResponseBody'
          description: 'Successfully retrieved key information.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Get API Key by Hash
      tags:
      - keys
      x-speakeasy-name-override: whoami
  /v2/liveness:
    get:
      description: 'Check if the Unkey API service is healthy and ready to handle requests.


        Use this for load balancer health checks, monitoring systems, and orchestration platforms. No authentication required
        with minimal processing overhead.


        **Required Permissions**


        None - this endpoint requires no authentication.


        **Side Effects**


        None - this is a read-only health check that does not modify any data or state.

        '
      operationId: liveness
      responses:
        '200':
          content:
            application/json:
              examples:
                healthy:
                  summary: Healthy service
                  value:
                    data:
                      message: OK
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
              schema:
                $ref: '#/components/schemas/V2LivenessResponseBody'
          description: 'Service is healthy and ready to process requests. Returns ''OK'' message for normal operation.

            '
        '412':
          content:
            application/json:
              examples:
                degraded:
                  summary: Service in degraded state
                  value:
                    error:
                      detail: Service is in a degraded state. Some functionality may be limited.
                      status: 412
                      title: Precondition Failed
                      type: https://unkey.dev/errors/precondition-failed
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              examples:
                unhealthy:
                  summary: Service unhealthy
                  value:
                    error:
                      detail: The service is currently experiencing issues and may not be fully operational.
                      status: 500
                      title: Internal Server Error
                      type: https://unkey.dev/errors/internal-server-error
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQY
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: 'Service is unhealthy and unable to process requests properly. Significant service issue requiring
            immediate attention.

            '
      security: []
      summary: Health Check
      tags:
      - liveness
      x-excluded: true
      x-speakeasy-ignore: true
  /v2/permissions.createPermission:
    post:
      description: 'Create a new permission to define specific actions or capabilities in your RBAC system. Permissions can
        be assigned directly to API keys or included in roles.


        Use hierarchical naming patterns like `documents.read`, `admin.users.delete`, or `billing.invoices.create` for clear
        organization.


        **Important:** Permission names must be unique within the workspace. Once created, permissions are immediately available
        for assignment.


        **Required Permissions**


        Your root key must have the following permission:

        - `rbac.*.create_permission`

        '
      operationId: permissions.createPermission
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2PermissionsCreatePermissionRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PermissionsCreatePermissionResponseBody'
          description: Permission created successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
          description: Conflict - permission with that name already exists
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: Create Permission
      tags:
      - permissions
      x-speakeasy-name-override: CreatePermission
  /v2/permissions.createRole:
    post:
      description: 'Create a new role to group related permissions for easier management. Roles enable consistent permission
        assignment across multiple API keys.


        **Important:** Role names must be unique within the workspace. Once created, roles are immediately available for assignment.


        **Required Permissions**


        Your root key must have the following permission:

        - `rbac.*.create_role`

        '
      operationId: permissions.createRole
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: Basic role creation
                value:
                  description: Can read and write content
                  name: content.editor
              withoutDescription:
                summary: Role without description
                value:
                  name: api.reader
            schema:
              $ref: '#/components/schemas/V2PermissionsCreateRoleRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PermissionsCreateRoleResponseBody'
          description: Role created successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
          description: Conflict - A role with this name already exists
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: Create Role
      tags:
      - permissions
      x-speakeasy-name-override: CreateRole
  /v2/permissions.deletePermission:
    post:
      description: 'Remove a permission from your workspace. This also removes the permission from all API keys and roles.


        **Important:** This operation cannot be undone and immediately affects all API keys and roles that had this permission
        assigned.


        **Required Permissions**


        Your root key must have the following permission:

        - `rbac.*.delete_permission`

        '
      operationId: permissions.deletePermission
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: Delete a permission
                value:
                  permissionId: perm_1234567890abcdef
            schema:
              $ref: '#/components/schemas/V2PermissionsDeletePermissionRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PermissionsDeletePermissionResponseBody'
          description: Permission deleted successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found - The specified permission does not exist
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: Delete Permission
      tags:
      - permissions
      x-speakeasy-name-override: DeletePermission
  /v2/permissions.deleteRole:
    post:
      description: 'Remove a role from your workspace. This also removes the role from all assigned API keys.


        **Important:** This operation cannot be undone and immediately affects all API keys that had this role assigned.


        **Required Permissions**


        Your root key must have the following permission:

        - `rbac.*.delete_role`

        '
      operationId: permissions.deleteRole
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2PermissionsDeleteRoleRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PermissionsDeleteRoleResponseBody'
          description: Role deleted successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: Delete Role
      tags:
      - permissions
      x-speakeasy-name-override: DeleteRole
  /v2/permissions.getPermission:
    post:
      description: 'Retrieve details about a specific permission including its name, description, and metadata.


        **Required Permissions**


        Your root key must have the following permission:

        - `rbac.*.read_permission`

        '
      operationId: permissions.getPermission
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2PermissionsGetPermissionRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PermissionsGetPermissionResponseBody'
          description: Permission retrieved successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: Get Permission
      tags:
      - permissions
      x-speakeasy-name-override: GetPermission
  /v2/permissions.getRole:
    post:
      description: 'Retrieve details about a specific role including its assigned permissions.


        **Required Permissions**


        Your root key must have the following permission:

        - `rbac.*.read_role`

        '
      operationId: permissions.getRole
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2PermissionsGetRoleRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PermissionsGetRoleResponseBody'
          description: Role retrieved successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: Get Role
      tags:
      - permissions
      x-speakeasy-name-override: GetRole
  /v2/permissions.listPermissions:
    post:
      description: 'Retrieve all permissions in your workspace.

        Results are paginated and sorted by their id.


        **Required Permissions**


        Your root key must have the following permission:

        - `rbac.*.read_permission`

        '
      operationId: permissions.listPermissions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2PermissionsListPermissionsRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PermissionsListPermissionsResponseBody'
          description: Permissions retrieved successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: List Permissions
      tags:
      - permissions
      x-speakeasy-name-override: ListPermissions
  /v2/permissions.listRoles:
    post:
      description: 'Retrieve all roles in your workspace including their assigned permissions.

        Results are paginated and sorted by their id.


        **Required Permissions**


        Your root key must have the following permission:

        - `rbac.*.read_role`

        '
      operationId: permissions.listRoles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2PermissionsListRolesRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2PermissionsListRolesResponseBody'
          description: Roles retrieved successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: List Roles
      tags:
      - permissions
      x-speakeasy-name-override: ListRoles
  /v2/ratelimit.deleteOverride:
    post:
      description: 'Permanently remove a rate limit override. Affected identifiers immediately revert to the namespace default.


        Use this to remove temporary overrides, reset identifiers to standard limits, or clean up outdated rules.


        **Important:** Deletion is immediate and permanent. The override cannot be recovered and must be recreated if needed
        again.


        **Permissions:** Requires `ratelimit.*.delete_override` or `ratelimit.<namespace_id>.delete_override`

        '
      operationId: ratelimit.deleteOverride
      requestBody:
        content:
          application/json:
            examples:
              specific:
                summary: Delete specific override
                value:
                  identifier: premium_user_123
                  namespace: api.requests
              wildcard:
                summary: Delete wildcard pattern override
                value:
                  identifier: premium_*
                  namespace: api.requests
            schema:
              $ref: '#/components/schemas/V2RatelimitDeleteOverrideRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2RatelimitDeleteOverrideResponseBody'
          description: Override successfully deleted. Affected identifiers now use default limits.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              examples:
                missingPermission:
                  summary: Missing required permission
                  value:
                    error:
                      detail: Your root key requires the 'ratelimit.*.delete_override' permission to perform this operation
                      status: 403
                      title: Forbidden
                      type: forbidden
                    meta:
                      requestId: req_0uVwX4yZaAbCdEfGhIjKl
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden - Insufficient permissions (requires `ratelimit.*.delete_override`)
        '404':
          content:
            application/json:
              examples:
                overrideNotFound:
                  summary: Override not found
                  value:
                    error:
                      detail: No override found for the specified identifier in this namespace.
                      status: 404
                      title: Not Found
                      type: not_found
                    meta:
                      requestId: req_2wXyZaAbCdEfGhIjKlMnOp
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found - Override or namespace not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: Delete Ratelimit Override
      tags:
      - ratelimit
      x-speakeasy-name-override: deleteOverride
  /v2/ratelimit.getOverride:
    post:
      description: 'Retrieve the configuration of a specific rate limit override by its identifier.


        Use this to inspect override configurations, audit rate limiting policies, or debug rate limiting behavior.


        **Important:** The identifier must match exactly as specified when creating the override, including wildcard patterns.


        **Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`

        '
      operationId: ratelimit.getOverride
      requestBody:
        content:
          application/json:
            examples:
              specific:
                summary: Get specific override
                value:
                  identifier: premium_user_123
                  namespace: api.requests
              wildcard:
                summary: Get wildcard pattern override
                value:
                  identifier: premium_*
                  namespace: api.requests
            schema:
              $ref: '#/components/schemas/V2RatelimitGetOverrideRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2RatelimitGetOverrideResponseBody'
          description: Override found and returned successfully.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              examples:
                missingPermission:
                  summary: Missing required permission
                  value:
                    error:
                      detail: Your root key requires the 'ratelimit.*.read_override' permission to perform this operation
                      status: 403
                      title: Forbidden
                      type: forbidden
                    meta:
                      requestId: req_0uVwX4yZaAbCdEfGhIjKl
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden - Insufficient permissions (requires `ratelimit.*.read_override`)
        '404':
          content:
            application/json:
              examples:
                overrideNotFound:
                  summary: Override not found
                  value:
                    error:
                      detail: No override found for the specified identifier in this namespace.
                      status: 404
                      title: Not Found
                      type: not_found
                    meta:
                      requestId: req_2wXyZaAbCdEfGhIjKlMnOp
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found - Override or namespace not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: Get Ratelimit Override
      tags:
      - ratelimit
      x-speakeasy-name-override: getOverride
  /v2/ratelimit.limit:
    post:
      description: 'Check and enforce rate limits for any identifier (user ID, IP address, API client, etc.).


        Use this for rate limiting beyond API keys - limit users by ID, IPs by address, or any custom identifier. Supports
        namespace organization, variable costs, and custom overrides.


        **Response Codes**: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded — check the `success`
        field in the response to determine if the request should be allowed. A 429 may be returned if the workspace exceeds
        its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410
        Gone for deleted namespaces). 5xx responses indicate server errors.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `ratelimit.*.limit` (to check limits in any namespace)

        - `ratelimit.<namespace_id>.limit` (to check limits in a specific namespace)

        '
      operationId: ratelimit.limit
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: Basic rate limit check
                value:
                  duration: 60000
                  identifier: user_abc123
                  limit: 100
                  namespace: api.requests
              ipLimit:
                summary: IP-based rate limiting
                value:
                  duration: 60000
                  identifier: 203.0.113.42
                  limit: 5
                  namespace: auth.login
              weightedCost:
                summary: Operation with variable cost
                value:
                  cost: 5
                  duration: 3600000
                  identifier: user_def456
                  limit: 50
                  namespace: api.heavy_operations
            schema:
              $ref: '#/components/schemas/V2RatelimitLimitRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                allowed:
                  summary: Request allowed
                  value:
                    data:
                      limit: 100
                      remaining: 99
                      reset: 1714582980000
                      success: true
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
                limitReached:
                  summary: Rate limit exceeded
                  value:
                    data:
                      limit: 100
                      remaining: 0
                      reset: 1714582980000
                      success: false
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQY
                withOverride:
                  summary: With custom override applied
                  value:
                    data:
                      limit: 1000
                      overrideId: ovr_2cGKbMxRyIzhCxo1Idjz8q
                      remaining: 995
                      reset: 1714582980000
                      success: true
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQZ
              schema:
                $ref: '#/components/schemas/V2RatelimitLimitResponseBody'
          description: 'Rate limit check completed successfully. Check the `success` field to determine if the request is
            allowed.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoneErrorResponse'
          description: Gone - Namespace has been deleted
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Apply Rate Limiting
      tags:
      - ratelimit
      x-speakeasy-name-override: limit
  /v2/ratelimit.listOverrides:
    post:
      description: 'Retrieve a paginated list of all rate limit overrides in a namespace.


        Use this to audit rate limiting policies, build admin dashboards, or manage override configurations.


        **Important:** Results are paginated. Use the cursor parameter to retrieve additional pages when more results are
        available.


        **Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`

        '
      operationId: ratelimit.listOverrides
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: List all overrides
                value:
                  limit: 20
                  namespace: api.requests
              pagination:
                summary: Get next page
                value:
                  cursor: cursor_eyJsYXN0SWQiOiJvdnJfM2RITGNOeVN6SnppRHlwMkpla2E5ciJ9
                  namespace: api.requests
            schema:
              $ref: '#/components/schemas/V2RatelimitListOverridesRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2RatelimitListOverridesResponseBody'
          description: Overrides retrieved successfully. Includes pagination metadata if more results are available.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              examples:
                missingPermission:
                  summary: Missing required permission
                  value:
                    error:
                      detail: Your root key requires the 'ratelimit.*.read_override' permission to perform this operation
                      status: 403
                      title: Forbidden
                      type: forbidden
                    meta:
                      requestId: req_0uVwX4yZaAbCdEfGhIjKl
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden - Insufficient permissions (requires `ratelimit.*.read_override`)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Error
      security:
      - rootKey: []
      summary: List Ratelimit Overrides
      tags:
      - ratelimit
      x-speakeasy-name-override: listOverrides
  /v2/ratelimit.multiLimit:
    post:
      description: 'Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses,
        API clients, etc.).


        Use this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own
        result with a top-level `passed` indicator showing if all checks succeeded.


        **Response Codes**: Rate limit checks return HTTP 200 regardless of whether limits are exceeded — check the `passed`
        field to see if all limits passed, or the `success` field in each individual result. A 429 may be returned if the
        workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation
        errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.


        **Required Permissions**


        Your root key must have one of the following permissions:

        - `ratelimit.*.limit` (to check limits in any namespace)

        - `ratelimit.<namespace_id>.limit` (to check limits in all specific namespaces being checked)

        '
      operationId: ratelimit.multiLimit
      requestBody:
        content:
          application/json:
            examples:
              ipHashAndUserLimits:
                summary: Check both hashed IP and user rate limits
                value:
                - duration: 60000
                  identifier: sha256_8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4
                  limit: 10
                  namespace: auth.login
                - duration: 3600000
                  identifier: user_def456
                  limit: 1000
                  namespace: api.requests
              multipleChecks:
                summary: Multiple rate limit checks
                value:
                - duration: 60000
                  identifier: user_abc123
                  limit: 100
                  namespace: api.requests
                - duration: 60000
                  identifier: user_abc123
                  limit: 5
                  namespace: auth.login
              withWeightedCost:
                summary: Multiple checks with variable costs
                value:
                - cost: 1
                  duration: 60000
                  identifier: user_xyz789
                  limit: 100
                  namespace: api.light_operations
                - cost: 5
                  duration: 3600000
                  identifier: user_xyz789
                  limit: 50
                  namespace: api.heavy_operations
            schema:
              $ref: '#/components/schemas/V2RatelimitMultiLimitRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                allAllowed:
                  summary: All requests allowed
                  value:
                    data:
                      limits:
                      - identifier: user_abc123
                        limit: 100
                        namespace: api.requests
                        remaining: 99
                        reset: 1714582980000
                        success: true
                      - identifier: user_abc123
                        limit: 5
                        namespace: auth.login
                        remaining: 4
                        reset: 1714582980000
                        success: true
                      passed: true
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
                mixedResults:
                  summary: Some limits exceeded
                  value:
                    data:
                      limits:
                      - identifier: sha256_8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4
                        limit: 10
                        namespace: auth.login
                        remaining: 5
                        reset: 1714582980000
                        success: true
                      - identifier: user_def456
                        limit: 1000
                        namespace: api.requests
                        remaining: 0
                        reset: 1714583040000
                        success: false
                      passed: false
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQY
                withOverride:
                  summary: With custom override applied
                  value:
                    data:
                      limits:
                      - identifier: user_xyz789
                        limit: 100
                        namespace: api.light_operations
                        remaining: 95
                        reset: 1714582980000
                        success: true
                      - identifier: user_xyz789
                        limit: 1000
                        namespace: api.heavy_operations
                        overrideId: ovr_2cGKbMxRyIzhCxo1Idjz8q
                        remaining: 995
                        reset: 1714582980000
                        success: true
                      passed: true
                    meta:
                      requestId: req_01H9TQPP77V5E48E9SH0BG0ZQZ
              schema:
                $ref: '#/components/schemas/V2RatelimitMultiLimitResponseBody'
          description: 'All rate limit checks completed successfully. Check the `success` field in each result to determine
            if the corresponding request is allowed.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoneErrorResponse'
          description: Gone - Namespace has been deleted
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal server error
      security:
      - rootKey: []
      summary: Apply Multiple Rate Limit Checks
      tags:
      - ratelimit
      x-speakeasy-name-override: multiLimit
  /v2/ratelimit.setOverride:
    post:
      description: 'Create or update a custom rate limit for specific identifiers, bypassing the namespace default.


        Use this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency
        throttling.


        **Important:** Overrides take effect immediately and completely replace the default limit for matching identifiers.
        Use wildcard patterns (e.g., `premium_*`) to match multiple identifiers.


        **Permissions:** Requires `ratelimit.*.set_override` or `ratelimit.<namespace_id>.set_override`

        '
      operationId: ratelimit.setOverride
      requestBody:
        content:
          application/json:
            examples:
              premium:
                summary: Higher limit for premium user
                value:
                  duration: 60000
                  identifier: premium_user_123
                  limit: 1000
                  namespace: api.requests
              wildcard:
                summary: Pattern for multiple identifiers
                value:
                  duration: 60000
                  identifier: premium_*
                  limit: 500
                  namespace: api.requests
            schema:
              $ref: '#/components/schemas/V2RatelimitSetOverrideRequestBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2RatelimitSetOverrideResponseBody'
          description: Override successfully created or updated and is now active.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              examples:
                missingPermission:
                  summary: Missing required permission
                  value:
                    error:
                      detail: Your root key requires the 'ratelimit.*.set_override' permission to perform this operation
                      status: 403
                      title: Forbidden
                      type: forbidden
                    meta:
                      requestId: req_0uVwX4yZaAbCdEfGhIjKl
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
          description: Forbidden - Insufficient permissions (requires `ratelimit.*.set_override`)
        '404':
          content:
            application/json:
              examples:
                namespaceNotFound:
                  summary: Namespace not found
                  value:
                    error:
                      detail: This namespace does not exist.
                      status: 404
                      title: Not Found
                      type: not_found
                    meta:
                      requestId: req_2wXyZaAbCdEfGhIjKlMnOp
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
          description: Not Found - Namespace not found
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Internal Server Error
      security:
      - rootKey: []
      summary: Set Ratelimit Override
      tags:
      - ratelimit
      x-speakeasy-name-override: setOverride
components:
  securitySchemes:
    rootKey:
      bearerFormat: root key
      description: 'Unkey uses API keys (root keys) for authentication. These keys authorize access to management operations
        in the API.

        To authenticate, include your root key in the Authorization header of each request:

        ```

        Authorization: Bearer unkey_123

        ```

        Root keys have specific permissions attached to them, controlling what operations they can perform. Key permissions
        follow a hierarchical structure with patterns like `resource.resource_id.action` (e.g., `apis.*.create_key`, `apis.*.read_api`).

        Security best practices:

        - Keep root keys secure and never expose them in client-side code

        - Use different root keys for different environments

        - Rotate keys periodically, especially after team member departures

        - Create keys with minimal necessary permissions following least privilege principle

        - Monitor key usage with audit logs.'
      scheme: bearer
      type: http
  schemas:
    V2AnalyticsGetVerificationsRequestBody:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: 'SQL query to execute against your analytics data.

            Only SELECT queries are allowed.

            '
          example: SELECT COUNT(*) as total FROM key_verifications_v1 WHERE outcome = 'VALID' AND time >= now() - INTERVAL
            7 DAY
    V2AnalyticsGetVerificationsResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2AnalyticsGetVerificationsResponseData'
    BadRequestErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BadRequestErrorDetails'
      description: Error response for invalid requests that cannot be processed due to client-side errors. This typically
        occurs when request parameters are missing, malformed, or fail validation rules. The response includes detailed information
        about the specific errors in the request, including the location of each error and suggestions for fixing it. When
        receiving this error, check the 'errors' array in the response for specific validation issues that need to be addressed
        before retrying.
    UnauthorizedErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when authentication has failed or credentials are missing. This occurs when:

        - No authentication token is provided in the request

        - The provided token is invalid, expired, or malformed

        - The token format doesn''t match expected patterns


        To resolve this error, ensure you''re including a valid root key in the Authorization header.'
    ForbiddenErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when the provided credentials are valid but lack sufficient permissions for the requested
        operation. This occurs when:

        - The root key doesn''t have the required permissions for this endpoint

        - The operation requires elevated privileges that the current key lacks

        - Access to the requested resource is restricted based on workspace settings


        To resolve this error, ensure your root key has the necessary permissions or contact your workspace administrator.'
    NotFoundErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when the requested resource cannot be found. This occurs when:

        - The specified resource ID doesn''t exist in your workspace

        - The resource has been deleted or moved

        - The resource exists but is not accessible with current permissions


        To resolve this error, verify the resource ID is correct and that you have access to it.'
    UnprocessableEntityErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when the request is syntactically valid but cannot be processed due to semantic constraints
        or resource limitations. This occurs when:

        - A query exceeds execution time limits

        - A query uses more memory than allowed

        - A query scans too many rows

        - A query result exceeds size limits


        The request syntax is correct, but the operation cannot be completed due to business rules or resource constraints.
        Review the error details for specific limitations and adjust your request accordingly.'
    TooManyRequestsErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when the client has sent too many requests in a given time period. This occurs when you''ve
        exceeded a rate limit or quota for the resource you''re accessing.


        The rate limit resets automatically after the time window expires. To avoid this error:

        - Implement exponential backoff when retrying requests

        - Cache results where appropriate to reduce request frequency

        - Check the error detail message for specific quota information

        - Contact support if you need a higher quota for your use case'
    InternalServerErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when an unexpected error occurs on the server. This indicates a problem with Unkey''s systems
        rather than your request.


        When you encounter this error:

        - The request ID in the response can help Unkey support investigate the issue

        - The error is likely temporary and retrying may succeed

        - If the error persists, contact Unkey support with the request ID'
    ServiceUnavailableErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when a required service is temporarily unavailable. This indicates that the service exists
        but cannot be reached or is not responding.


        When you encounter this error:

        - The service is likely experiencing temporary issues

        - Retrying the request after a short delay may succeed

        - If the error persists, the service may be undergoing maintenance

        - Contact Unkey support if the issue continues'
    V2ApisCreateApiRequestBody:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z][a-zA-Z0-9._-]*$
          description: 'Unique identifier for this API namespace within your workspace.

            Use descriptive names like ''payment-service-prod'' or ''user-api-dev'' to clearly identify purpose and environment.

            '
          example: payment-service-production
      additionalProperties: false
    V2ApisCreateApiResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2ApisCreateApiResponseData'
      additionalProperties: false
    V2ApisDeleteApiRequestBody:
      type: object
      required:
      - apiId
      properties:
        apiId:
          type: string
          minLength: 8
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which API namespace to permanently delete from your workspace.

            Must be a valid API ID that begins with ''api_'' and exists within your workspace.


            Before proceeding, ensure you have the correct API ID and understand that this action cannot be undone. If you
            need to migrate functionality, create replacement keys in a new API namespace and update client applications before
            deletion.

            '
          example: api_1234abcd
      additionalProperties: false
    V2ApisDeleteApiResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/EmptyResponse'
      additionalProperties: false
    PreconditionFailedErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when one or more conditions specified in the request headers are not met. This typically
        occurs when:

        - Using conditional requests with If-Match or If-None-Match headers

        - The resource version doesn''t match the expected value

        - Optimistic concurrency control detects a conflict


        To resolve this error, fetch the latest version of the resource and retry with updated conditions.'
    V2ApisGetApiRequestBody:
      type: object
      required:
      - apiId
      properties:
        apiId:
          type: string
          minLength: 8
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which API to retrieve by its unique identifier.

            Must be a valid API ID that begins with ''api_'' and exists within your workspace.

            '
          example: api_1234abcd
      additionalProperties: false
    V2ApisGetApiResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2ApisGetApiResponseData'
      additionalProperties: false
    V2ApisListKeysRequestBody:
      type: object
      required:
      - apiId
      properties:
        apiId:
          type: string
          minLength: 1
          description: 'The API namespace whose keys you want to list.

            Returns all keys in this API, subject to pagination and filters.

            '
          example: api_1234abcd
        limit:
          type: integer
          description: 'Maximum number of keys to return per request.

            Balance between response size and number of pagination calls needed.

            '
          default: 100
          minimum: 1
          maximum: 100
        cursor:
          type: string
          description: 'Pagination cursor from previous response to fetch next page.

            Use when `hasMore: true` in previous response.

            '
          example: key_1234abcd
        externalId:
          type: string
          minLength: 1
          description: 'Filter keys by external ID to find keys for a specific user or entity.

            Must exactly match the externalId set during key creation.

            '
          example: user_1234abcd
        decrypt:
          type: boolean
          description: 'When true, attempts to include the plaintext key value in the response. SECURITY WARNING:

            - This requires special permissions on the calling root key

            - Only works for keys created with ''recoverable: true''

            - Exposes sensitive key material in the response

            - Should only be used in secure administrative contexts

            - Never enable this in user-facing applications'
          default: false
        revalidateKeysCache:
          type: boolean
          default: false
          description: 'EXPERIMENTAL: Skip the cache and fetch the keys directly from the database. This ensures you see the
            most recent state, including keys created moments ago. Use this when:

            - You''ve just created a key and need to display it immediately

            - You need absolute certainty about the current key state

            - You''re debugging cache consistency issues


            This parameter comes with a performance cost and should be used sparingly.'
      additionalProperties: false
    V2ApisListKeysResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2ApisListKeysResponseData'
        pagination:
          $ref: '#/components/schemas/Pagination'
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      additionalProperties: false
    V2DeployCreateDeploymentRequestBody:
      type: object
      required:
      - project
      - app
      - branch
      - environmentSlug
      - dockerImage
      properties:
        project:
          type: string
          minLength: 1
          description: Project slug
          example: my-project
        app:
          type: string
          minLength: 1
          description: App slug within the project
          example: default
        keyspaceId:
          type: string
          description: Optional keyspace ID for authentication context
          example: key_abc123
        branch:
          type: string
          minLength: 1
          description: Git branch name
          example: main
        environmentSlug:
          type: string
          minLength: 1
          description: Environment slug (e.g., "production", "staging")
          example: production
        dockerImage:
          type: string
          minLength: 1
          description: Docker image reference to deploy
          example: ghcr.io/user/app:v1.0.0
        gitCommit:
          $ref: '#/components/schemas/V2DeployGitCommit'
      description: Create a deployment from a pre-built Docker image
    V2DeployCreateDeploymentResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2DeployCreateDeploymentResponseData'
    V2DeployGetDeploymentRequestBody:
      type: object
      required:
      - deploymentId
      properties:
        deploymentId:
          type: string
          minLength: 1
          description: Unique deployment identifier to retrieve
          example: d_abc123xyz
          pattern: ^d_[a-zA-Z0-9]+$
    V2DeployGetDeploymentResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2DeployGetDeploymentResponseData'
    V2IdentitiesCreateIdentityRequestBody:
      type: object
      required:
      - externalId
      properties:
        externalId:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[a-zA-Z0-9_.-]+$
          description: 'Creates an identity using your system''s unique identifier for a user, organization, or entity.

            Must be stable and unique across your workspace - duplicate externalIds return CONFLICT errors.

            This identifier links Unkey identities to your authentication system, database records, or tenant structure.


            Avoid changing externalIds after creation as this breaks the link between your systems.

            Use consistent identifier patterns across your application for easier management and debugging.

            Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.

            Essential for implementing proper multi-tenant isolation and user-specific rate limiting.

            '
          example: user_123
        meta:
          type: object
          additionalProperties: true
          maxProperties: 100
          description: 'Stores arbitrary JSON metadata returned during key verification for contextual information.

            Eliminates additional database lookups during verification, improving performance for stateless services.

            Avoid storing sensitive data here as it''s returned in verification responses.


            Large metadata objects increase verification latency and should stay under 10KB total size.

            Use this for subscription details, feature flags, user preferences, and organization information.

            Metadata is returned as-is whenever keys associated with this identity are verified.

            '
        ratelimits:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/RatelimitRequest'
          description: 'Defines shared rate limits that apply to all keys belonging to this identity.

            Prevents abuse by users with multiple keys by enforcing consistent limits across their entire key portfolio.

            Essential for implementing fair usage policies and tiered access levels in multi-tenant applications.


            Rate limit counters are shared across all keys with this identity, regardless of how many keys the user creates.

            During verification, specify which named limits to check for enforcement.

            Identity rate limits supplement any key-specific rate limits that may also be configured.

            - Each named limit can have different thresholds and windows


            When verifying keys, you can specify which limits you want to use and all keys attached to this identity will
            share the limits, regardless of which specific key is used.

            '
    V2IdentitiesCreateIdentityResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2IdentitiesCreateIdentityResponseData'
    ConflictErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when the request conflicts with the current state of the resource. This occurs when:

        - Attempting to create a resource that already exists

        - Modifying a resource that has been changed by another operation

        - Violating unique constraints or business rules


        To resolve this error, check the current state of the resource and adjust your request accordingly.'
    V2IdentitiesDeleteIdentityRequestBody:
      type: object
      properties:
        identity:
          type: string
          minLength: 1
          description: The ID of the identity to delete. This can be either the externalId (from your own system that was
            used during identity creation) or the identityId (the internal ID returned by the identity service).
          example: user_123
      additionalProperties: false
      required:
      - identity
    V2IdentitiesDeleteIdentityResponseBody:
      type: object
      description: Empty response object. A successful response indicates the identity was deleted successfully.
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - meta
    V2IdentitiesGetIdentityRequestBody:
      type: object
      properties:
        identity:
          type: string
          minLength: 1
          description: The ID of the identity to retrieve. This can be either the externalId (from your own system that was
            used during identity creation) or the identityId (the internal ID returned by the identity service).
          example: user_abc123
      additionalProperties: false
      required:
      - identity
    V2IdentitiesGetIdentityResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/Identity'
    V2IdentitiesListIdentitiesRequestBody:
      type: object
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
          description: The maximum number of identities to return in a single request. Use this to control response size and
            loading performance.
          example: 50
        cursor:
          type: string
          description: Pagination cursor from a previous response. Use this to fetch subsequent pages of results when the
            response contains a cursor value.
          example: cursor_eyJrZXkiOiJrZXlfMTIzNCJ9
      additionalProperties: false
    V2IdentitiesListIdentitiesResponseBody:
      type: object
      required:
      - meta
      - data
      - pagination
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2IdentitiesListIdentitiesResponseData'
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    V2IdentitiesUpdateIdentityRequestBody:
      type: object
      properties:
        identity:
          type: string
          minLength: 1
          description: The ID of the identity to update. Accepts either the externalId (your system-generated identifier)
            or the identityId (internal identifier returned by the identity service).
          example: user_123
        meta:
          type: object
          additionalProperties: true
          maxProperties: 100
          description: 'Replaces all existing metadata with this new metadata object.

            Omitting this field preserves existing metadata, while providing an empty object clears all metadata.

            Avoid storing sensitive data here as it''s returned in verification responses.

            Large metadata objects increase verification latency and should stay under 10KB total size.

            '
          example:
            name: Alice Smith
            email: alice@example.com
            plan: premium
        ratelimits:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/RatelimitRequest'
          description: 'Replaces all existing identity rate limits with this complete list of rate limits.

            Omitting this field preserves existing rate limits, while providing an empty array removes all rate limits.

            These limits are shared across all keys belonging to this identity, preventing abuse through multiple keys.

            Rate limit changes take effect immediately but may take up to 30 seconds to propagate across all regions.

            '
          example:
          - name: requests
            limit: 1000
            duration: 3600000
            autoApply: true
      additionalProperties: false
      required:
      - identity
    V2IdentitiesUpdateIdentityResponseBody:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          $ref: '#/components/schemas/Identity'
        meta:
          $ref: '#/components/schemas/Meta'
    V2KeysAddPermissionsRequestBody:
      type: object
      required:
      - keyId
      - permissions
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which key receives the additional permissions using the database identifier returned from
            `keys.createKey`.

            Do not confuse this with the actual API key string that users include in requests.

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        permissions:
          type: array
          minItems: 1
          maxItems: 1000
          description: 'Grants additional permissions to the key through direct assignment or automatic creation.

            Duplicate permissions are ignored automatically, making this operation idempotent.


            Adding permissions never removes existing permissions or role-based permissions.


            Any permissions that do not exist will be auto created if the root key has permissions, otherwise this operation
            will fail with a 403 error.

            '
          items:
            type: string
            minLength: 3
            pattern: ^[a-zA-Z0-9_:\-\.\*]+$
            description: Specify the permission by its slug.
      additionalProperties: false
    V2KeysAddPermissionsResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysAddPermissionsResponseData'
    V2KeysAddRolesRequestBody:
      type: object
      required:
      - keyId
      - roles
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which key receives the additional roles using the database identifier returned from `createKey`.

            Do not confuse this with the actual API key string that users include in requests.

            Added roles supplement existing roles and permissions without replacing them.

            Role assignments take effect immediately but may take up to 30 seconds to propagate across all regions.

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        roles:
          type: array
          minItems: 1
          maxItems: 100
          description: 'Assigns additional roles to the key through direct assignment to existing workspace roles.

            Operations are idempotent - adding existing roles has no effect and causes no errors.


            All roles must already exist in the workspace - roles cannot be created automatically.

            Invalid roles cause the entire operation to fail atomically, ensuring consistent state.

            '
          items:
            type: string
            minLength: 3
            maxLength: 255
            pattern: ^[a-zA-Z][a-zA-Z0-9._-]*$
            description: Specify the role by name.
      additionalProperties: false
    V2KeysAddRolesResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysAddRolesResponseData'
    V2KeysCreateKeyRequestBody:
      type: object
      required:
      - apiId
      properties:
        apiId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'The API namespace this key belongs to.

            Keys from different APIs cannot access each other.

            '
          example: api_1234abcd
        prefix:
          type: string
          minLength: 1
          maxLength: 16
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Adds a visual identifier to the beginning of the generated key for easier recognition in logs and
            dashboards.

            The prefix becomes part of the actual key string (e.g., `prod_xxxxxxxxx`).

            Avoid using sensitive information in prefixes as they may appear in logs and error messages.

            '
          example: prod
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: 'Sets a human-readable identifier for internal organization and dashboard display.

            Never exposed to end users, only visible in management interfaces and API responses.

            Avoid generic names like "API Key" when managing multiple keys for the same user or service.

            '
          example: Payment Service Production Key
        byteLength:
          type: integer
          minimum: 16
          maximum: 255
          default: 16
          description: 'Controls the cryptographic strength of the generated key in bytes.

            Higher values increase security but result in longer keys that may be more annoying to handle.

            The default 16 bytes provides 2^128 possible combinations, sufficient for most applications.

            Consider 32 bytes for highly sensitive APIs, but avoid values above 64 bytes unless specifically required.

            '
          example: 24
        externalId:
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[a-zA-Z0-9_.-]+$
          description: 'Links this key to a user or entity in your system using your own identifier.

            Returned during verification to identify the key owner without additional database lookups.

            Essential for user-specific analytics, billing, and multi-tenant key management.

            Use your primary user ID, organization ID, or tenant ID for best results.

            Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.

            '
          example: user_1234abcd
        meta:
          type: object
          additionalProperties: true
          maxProperties: 100
          description: 'Stores arbitrary JSON metadata returned during key verification for contextual information.

            Eliminates additional database lookups during verification, improving performance for stateless services.

            Avoid storing sensitive data here as it''s returned in verification responses.

            Large metadata objects increase verification latency and should stay under 10KB total size.

            '
          example:
            plan: enterprise
            featureFlags:
              betaAccess: true
              concurrentConnections: 10
            customerName: Acme Corp
            billing:
              tier: premium
              renewal: '2024-12-31'
        roles:
          type: array
          maxItems: 100
          items:
            type: string
            minLength: 1
            maxLength: 100
            pattern: ^[a-zA-Z0-9_:\-\.\*]+$
          description: 'Assigns existing roles to this key for permission management through role-based access control.

            Roles must already exist in your workspace before assignment.

            During verification, all permissions from assigned roles are checked against requested permissions.

            Roles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.

            '
          example:
          - api_admin
          - billing_reader
        permissions:
          type: array
          maxItems: 1000
          items:
            type: string
            minLength: 1
            maxLength: 100
          pattern: ^[a-zA-Z][a-zA-Z0-9._-]*$
          description: 'Grants specific permissions directly to this key without requiring role membership.

            Wildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.

            Direct permissions supplement any permissions inherited from assigned roles.

            '
          example:
          - documents.read
          - documents.write
          - settings.view
        expires:
          type: integer
          format: int64
          minimum: 0
          maximum: 4102444800000
          description: 'Sets when this key automatically expires as a Unix timestamp in milliseconds.

            Verification fails with code=EXPIRED immediately after this time passes.

            Omitting this field creates a permanent key that never expires.


            Avoid setting timestamps in the past as they immediately invalidate the key.

            Keys expire based on server time, not client time, which prevents timezone-related issues.

            Essential for trial periods, temporary access, and security compliance requiring key rotation.

            '
          example: 1704067200000
        credits:
          $ref: '#/components/schemas/KeyCreditsData'
          description: 'Controls usage-based limits through credit consumption with optional automatic refills.

            Unlike rate limits which control frequency, credits control total usage with global consistency.

            Essential for implementing usage-based pricing, subscription tiers, and hard usage quotas.

            Omitting this field creates unlimited usage, while setting null is not allowed during creation.

            '
        ratelimits:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/RatelimitRequest'
          description: 'Defines time-based rate limits that protect against abuse by controlling request frequency.

            Unlike credits which track total usage, rate limits reset automatically after each window expires.

            Multiple rate limits can control different operation types with separate thresholds and windows.

            Essential for preventing API abuse while maintaining good performance for legitimate usage.

            '
          example:
          - name: requests
            limit: 100
            duration: 60000
            autoApply: true
          - name: heavy_operations
            limit: 10
            duration: 3600000
            autoApply: false
        enabled:
          type: boolean
          default: true
          description: 'Controls whether the key is active immediately upon creation.

            When set to `false`, the key exists but all verification attempts fail with `code=DISABLED`.

            Useful for pre-creating keys that will be activated later or for keys requiring manual approval.

            Most keys should be created with `enabled=true` for immediate use.

            '
          example: true
        recoverable:
          type: boolean
          default: false
          description: 'Controls whether the plaintext key is stored in an encrypted vault for later retrieval.

            When true, allows recovering the actual key value using keys.getKey with decrypt=true.

            When false, the key value cannot be retrieved after creation for maximum security.

            Only enable for development keys or when key recovery is absolutely necessary.

            '
          example: false
      additionalProperties: false
    V2KeysCreateKeyResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysCreateKeyResponseData'
    V2KeysDeleteKeyRequestBody:
      type: object
      required:
      - keyId
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which key to delete using the database identifier returned from `createKey`.

            Do not confuse this with the actual API key string that users include in requests.

            Deletion immediately invalidates the key, causing all future verification attempts to fail with `code=NOT_FOUND`.

            Key deletion triggers cache invalidation across all regions but may take up to 30 seconds to fully propagate.

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        permanent:
          type: boolean
          default: false
          description: 'Controls deletion behavior between recoverable soft-deletion and irreversible permanent erasure.

            Soft deletion (default) preserves key data for potential recovery through direct database operations.

            Permanent deletion completely removes all traces including hash values and metadata with no recovery option.


            Use permanent deletion only for regulatory compliance (GDPR), resolving hash collisions, or when reusing identical
            key strings.

            Permanent deletion cannot be undone and may affect analytics data that references the deleted key.

            Most applications should use soft deletion to maintain audit trails and prevent accidental data loss.

            '
          example: false
      additionalProperties: false
    V2KeysDeleteKeyResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/EmptyResponse'
      additionalProperties: false
    V2KeysGetKeyRequestBody:
      type: object
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which key to retrieve using the database identifier returned from `keys.createKey`.

            Do not confuse this with the actual API key string that users include in requests.

            Key data includes metadata, permissions, usage statistics, and configuration but never the plaintext key value
            unless `decrypt=true`.

            Find this ID in creation responses, key listings, dashboard, or verification responses.

            '
          example: key_1234abcd
        decrypt:
          type: boolean
          default: false
          description: 'Controls whether to include the plaintext key value in the response for recovery purposes.

            Only works for keys created with `recoverable=true` and requires the `decrypt_key` permission.

            Returned keys must be handled securely, never logged, cached, or stored insecurely.


            Use only for legitimate recovery scenarios like user password resets or emergency access.

            Most applications should keep this false to maintain security best practices and avoid accidental key exposure.

            Decryption requests are audited and may trigger security alerts in enterprise environments.

            '
      additionalProperties: false
      required:
      - keyId
    V2KeysGetKeyResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/KeyResponseData'
    V2KeysMigrateKeysRequestBody:
      type: object
      properties:
        migrationId:
          type: string
          minLength: 3
          maxLength: 255
          description: Identifier of the configured migration provider/strategy to use (e.g., "your_company"). You will receive
            this from Unkey's support staff.
          example: your_company
        apiId:
          type: string
          minLength: 3
          maxLength: 255
          description: The ID of the API that the keys should be inserted into
          example: api_123456789
        keys:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/V2KeysMigrateKeyData'
      additionalProperties: false
      required:
      - migrationId
      - apiId
      - keys
    V2KeysMigrateKeysResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysMigrateKeysResponseData'
    V2KeysRemovePermissionsRequestBody:
      type: object
      required:
      - keyId
      - permissions
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which key to remove permissions from using the database identifier returned from `keys.createKey`.

            Do not confuse this with the actual API key string that users include in requests.

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        permissions:
          type: array
          minItems: 1
          maxItems: 1000
          description: 'Removes direct permissions from the key without affecting role-based permissions.


            You can either use a permission slug, or the permission ID.


            After removal, verification checks for these permissions will fail unless granted through roles.

            '
          items:
            type: string
            minLength: 3
            pattern: ^[a-zA-Z0-9_:\-\.\*]+$
            description: Specify the permission by its slug.
      additionalProperties: false
    V2KeysRemovePermissionsResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysRemovePermissionsResponseData'
    V2KeysRemoveRolesRequestBody:
      type: object
      required:
      - keyId
      - roles
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which key loses the roles using the database identifier returned from createKey.

            Do not confuse this with the actual API key string that users include in requests.

            Removing roles only affects direct assignments, not permissions inherited from other sources.

            Role changes take effect immediately but may take up to 30 seconds to propagate across all regions.

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        roles:
          type: array
          minItems: 1
          maxItems: 100
          description: 'Removes direct role assignments from the key without affecting other role sources or permissions.

            Operations are idempotent - removing non-assigned roles has no effect and causes no errors.


            After removal, the key loses access to permissions that were only granted through these roles.

            Invalid role references cause the entire operation to fail atomically, ensuring consistent state.

            '
          items:
            type: string
            pattern: ^[a-zA-Z0-9_:\-\.\*]+$
            minLength: 3
            maxLength: 255
            description: Specify the role by name.
      additionalProperties: false
    V2KeysRemoveRolesResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysRemoveRolesResponseData'
    V2KeysRerollKeyRequestBody:
      type: object
      required:
      - keyId
      - expiration
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'The database identifier of the key to reroll.


            This is the unique ID returned when creating or listing keys, NOT the actual API key token.

            You can find this ID in:

            - The response from `keys.createKey`

            - Key verification responses

            - The Unkey dashboard

            - API key listing endpoints

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        expiration:
          type: integer
          format: int64
          minimum: 0
          maximum: 4102444800000
          description: 'Duration in milliseconds until the ORIGINAL key is revoked, starting from now.


            This parameter controls the overlap period for key rotation:

            - Set to `0` to revoke the original key immediately

            - Positive values keep the original key active for the specified duration

            - Allows graceful migration by giving users time to update their credentials


            Common overlap periods:

            - Immediate revocation: 0

            - 1 hour grace period: 3600000

            - 24 hours grace period: 86400000

            - 7 days grace period: 604800000

            - 30 days grace period: 2592000000

            '
          example: 86400000
    V2KeysRerollKeyResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysRerollKeyResponseData'
    V2KeysSetPermissionsRequestBody:
      type: object
      required:
      - keyId
      - permissions
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which key receives the additional permissions using the database identifier returned from
            `keys.createKey`.

            Do not confuse this with the actual API key string that users include in requests.

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        permissions:
          type: array
          description: 'The permissions to set for this key.


            This is a complete replacement operation - it overwrites all existing direct permissions with this new set.


            Key behaviors:

            - Providing an empty array removes all direct permissions from the key

            - This only affects direct permissions - permissions granted through roles are not affected

            - All existing direct permissions not included in this list will be removed


            Any permissions that do not exist will be auto created if the root key has permissions, otherwise this operation
            will fail with a 403 error.'
          items:
            type: string
            minLength: 3
            pattern: ^[a-zA-Z0-9_:\-\.\*]+$
            description: Specify the permission by its slug.
      additionalProperties: false
    V2KeysSetPermissionsResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysSetPermissionsResponseData'
    V2KeysSetRolesRequestBody:
      type: object
      required:
      - keyId
      - roles
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which key gets the complete role replacement using the database identifier returned from
            createKey.

            Do not confuse this with the actual API key string that users include in requests.

            This is a wholesale replacement operation that removes all existing roles not included in the request.

            Role changes take effect immediately but may take up to 30 seconds to propagate across all regions.

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        roles:
          type: array
          maxItems: 100
          description: 'Replaces all existing role assignments with this complete list of roles.

            This is a wholesale replacement operation, not an incremental update like add/remove operations.


            Providing an empty array removes all direct role assignments from the key.

            All roles must already exist in the workspace - roles cannot be created automatically.

            Invalid role references cause the entire operation to fail atomically, ensuring consistent state.

            '
          items:
            type: string
            pattern: ^[a-zA-Z0-9_:\-\.\*]+$
            minLength: 3
            maxLength: 255
            description: Specify the role by name.
      additionalProperties: false
    V2KeysSetRolesResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysSetRolesResponseData'
    V2KeysUpdateCreditsRequestBody:
      type: object
      required:
      - keyId
      - operation
      properties:
        keyId:
          type: string
          description: The ID of the key to update (begins with `key_`). This is the database reference ID for the key, not
            the actual API key string that users authenticate with. This ID uniquely identifies which key's credits will be
            updated.
          example: key_2cGKbMxRyIzhCxo1Idjz8q
          minLength: 3
        value:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 0
          maximum: 9223372036854776000
          description: 'The credit value to use with the specified operation. The meaning depends on the operation: for ''set'',
            this becomes the new remaining credits value; for ''increment'', this amount is added to current credits; for
            ''decrement'', this amount is subtracted from current credits.


            Set to null when using ''set'' operation to make the key unlimited (removes usage restrictions entirely). When
            decrementing, if the result would be negative, remaining credits are automatically set to zero. Credits are consumed
            during successful key verification, and when credits reach zero, verification fails with `code=USAGE_EXCEEDED`.


            Required when using ''increment'' or ''decrement'' operations. Optional for ''set'' operation (null creates unlimited
            usage).

            '
          example: 1000
        operation:
          type: string
          enum:
          - set
          - increment
          - decrement
          x-speakeasy-unknown-values: allow
          description: 'Defines how to modify the key''s remaining credits. Use ''set'' to replace current credits with a
            specific value or unlimited usage, ''increment'' to add credits for plan upgrades or credit purchases, and ''decrement''
            to reduce credits for refunds or policy violations.

            '
          example: set
      additionalProperties: false
    V2KeysUpdateCreditsResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/KeyCreditsData'
      additionalProperties: false
    V2KeysUpdateKeyRequestBody:
      type: object
      required:
      - keyId
      properties:
        keyId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'Specifies which key to update using the database identifier returned from `createKey`.

            Do not confuse this with the actual API key string that users include in requests.

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        name:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 255
          description: 'Sets a human-readable name for internal organization and identification.

            Omitting this field leaves the current name unchanged, while setting null removes it entirely.

            Avoid generic names like "API Key" when managing multiple keys per user or service.

            '
          example: Payment Service Production Key
        externalId:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 255
          pattern: ^[a-zA-Z0-9_.-]+$
          description: 'Links this key to a user or entity in your system for ownership tracking during verification.

            Omitting this field preserves the current association, while setting null disconnects the key from any identity.

            Essential for user-specific analytics, billing, and key management across multiple users.

            Supports letters, numbers, underscores, dots, and hyphens for flexible identifier formats.

            '
          example: user_912a841d
        meta:
          type:
          - object
          - 'null'
          additionalProperties: true
          maxProperties: 100
          description: 'Stores arbitrary JSON metadata returned during key verification.

            Omitting this field preserves existing metadata, while setting null removes all metadata entirely.

            Avoid storing sensitive data here as it''s returned in verification responses.

            Large metadata objects increase verification latency and should stay under 10KB total size.

            '
          example:
            plan: enterprise
            limits:
              storage: 500GB
              compute: 1000 minutes/month
            features:
            - analytics
            - exports
            - webhooks
            hasAcceptedTerms: true
            billing:
              cycle: monthly
              next_billing: '2024-01-15'
            preferences:
              timezone: UTC
              notifications: true
            lastBillingDate: '2023-10-15'
        expires:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 0
          maximum: 4102444800000
          description: 'Sets when this key automatically expires as a Unix timestamp in milliseconds.

            Verification fails with code=EXPIRED immediately after this time passes.

            Omitting this field preserves the current expiration, while setting null makes the key permanent.


            Avoid setting timestamps in the past as they immediately invalidate the key.

            Keys expire based on server time, not client time, which prevents timezone-related issues.

            Active sessions continue until their next verification attempt after expiry.

            '
          example: 1704067200000
        credits:
          $ref: '#/components/schemas/UpdateKeyCreditsData'
          description: 'Controls usage-based limits for this key through credit consumption.

            Omitting this field preserves current credit settings, while setting null enables unlimited usage.

            Cannot configure refill settings when credits is null, and refillDay requires monthly interval.

            Essential for implementing usage-based pricing and subscription quotas.

            '
        ratelimits:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/RatelimitRequest'
          description: 'Defines time-based rate limits that protect against abuse by controlling request frequency.

            Omitting this field preserves existing rate limits, while setting null removes all rate limits.

            Unlike credits which track total usage, rate limits reset automatically after each window expires.

            Multiple rate limits can control different operation types with separate thresholds and windows.

            '
        enabled:
          type: boolean
          description: 'Controls whether the key is currently active for verification requests.

            When set to `false`, all verification attempts fail with `code=DISABLED` regardless of other settings.

            Omitting this field preserves the current enabled status.

            Useful for temporarily suspending access during billing issues, security incidents, or maintenance windows without
            losing key configuration.

            '
          example: true
        roles:
          type: array
          maxItems: 100
          items:
            type: string
            minLength: 1
            maxLength: 100
            pattern: ^[a-zA-Z0-9_:\-\.\*]+$
            description: 'Assigns existing roles to this key for permission management through role-based access control.

              Roles must already exist in your workspace before assignment.

              During verification, all permissions from assigned roles are checked against requested permissions.

              Roles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.

              '
          example:
          - api_admin
          - billing_reader
        permissions:
          type: array
          maxItems: 1000
          items:
            type: string
            minLength: 3
            maxLength: 100
            pattern: ^[a-zA-Z0-9_:\-\.\*]+$
            description: 'Grants specific permissions directly to this key without requiring role membership.

              Wildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.

              Direct permissions supplement any permissions inherited from assigned roles.

              '
          example:
          - documents.read
          - documents.write
          - settings.view
      additionalProperties: false
    V2KeysUpdateKeyResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/EmptyResponse'
      additionalProperties: false
    V2KeysVerifyKeyRequestBody:
      type: object
      additionalProperties: false
      required:
      - key
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 512
          description: 'The API key to verify, exactly as provided by your user.

            Include any prefix - even small changes will cause verification to fail.

            '
          example: sk_1234abcdef
        tags:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 512
          maxItems: 20
          description: 'Attaches metadata tags for analytics and monitoring without affecting verification outcomes.

            Enables segmentation of API usage in dashboards by endpoint, client version, region, or custom dimensions.

            Use ''key=value'' format for compatibility with most analytics tools and clear categorization.

            Avoid including sensitive data in tags as they may appear in logs and analytics reports.

            '
          example:
          - endpoint=/users/profile
          - method=GET
          - region=us-east-1
          - clientVersion=2.3.0
          - feature=premium
        permissions:
          type: string
          minLength: 1
          maxLength: 1000
          description: 'Checks if the key has the specified permission(s) using a query syntax.

            Supports single permissions, logical operators (AND, OR), and parentheses for grouping.

            Examples:

            - Single permission: "documents.read"

            - Multiple permissions: "documents.read AND documents.write"

            - Complex queries: "(documents.read OR documents.write) AND users.view"

            Verification fails if the key lacks the required permissions through direct assignment or role inheritance.

            '
          example: documents.read AND users.view
        credits:
          $ref: '#/components/schemas/KeysVerifyKeyCredits'
        ratelimits:
          type: array
          items:
            $ref: '#/components/schemas/KeysVerifyKeyRatelimit'
          description: 'Enforces time-based rate limiting during verification to prevent abuse and ensure fair usage.

            Omitting this field skips rate limit checks entirely, relying only on configured key rate limits.

            Multiple rate limits can be checked simultaneously, each with different costs and temporary overrides.

            Rate limit checks are optimized for performance but may allow brief bursts during high concurrency.

            '
        migrationId:
          type: string
          maxLength: 256
          description: Migrate keys on demand from your previous system. Reach out for migration support at support@unkey.dev
          example: m_1234abcd
    V2KeysVerifyKeyResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2KeysVerifyKeyResponseData'
      additionalProperties: false
    V2KeysWhoamiRequestBody:
      type: object
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 512
          description: 'The complete API key string provided by you, including any prefix.

            Never log, cache, or store API keys in your system as they provide full access to user resources.

            Include the full key exactly as provided - even minor modifications will cause a not found error.

            '
          example: sk_1234abcdef5678
      additionalProperties: false
      required:
      - key
    V2KeysWhoamiResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/KeyResponseData'
    V2LivenessResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2LivenessResponseData'
    V2PermissionsCreatePermissionRequestBody:
      type: object
      required:
      - name
      - slug
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 512
          description: 'Creates a permission with this human-readable name that describes its purpose.

            Names must be unique within your workspace to prevent conflicts during assignment.

            Use clear, semantic names that developers can easily understand when building authorization logic.

            Consider using hierarchical naming conventions like ''resource.action'' for better organization.


            Examples: ''users.read'', ''billing.write'', ''analytics.view'', ''admin.manage''

            '
          example: users.read
        slug:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[a-zA-Z][a-zA-Z0-9._-]*$
          description: 'Creates a URL-safe identifier for this permission that can be used in APIs and integrations.

            Must start with a letter and contain only letters, numbers, periods, underscores, and hyphens.

            Slugs are often used in REST endpoints, configuration files, and external integrations.

            Should closely match the name but in a format suitable for technical usage.

            Must be unique within your workspace to ensure reliable permission lookups.


            Keep slugs concise but descriptive for better developer experience.

            '
          example: users-read
        description:
          type: string
          maxLength: 512
          description: 'Provides detailed documentation of what this permission grants access to.

            Include information about affected resources, allowed actions, and any important limitations.

            This internal documentation helps team members understand permission scope and security implications.

            Not visible to end users - designed for development teams and security audits.


            Consider documenting:

            - What resources can be accessed

            - What operations are permitted

            - Any conditions or limitations

            - Related permissions that might be needed

            '
          example: Grants read-only access to user profile information, account settings, and subscription status.
      additionalProperties: false
    V2PermissionsCreatePermissionResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2PermissionsCreatePermissionResponseData'
      additionalProperties: false
    V2PermissionsCreateRoleRequestBody:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 512
          pattern: ^[a-zA-Z][a-zA-Z0-9._-]*$
          description: 'The unique name for this role. Must be unique within your workspace and clearly indicate the role''s
            purpose. Use descriptive names like ''admin'', ''editor'', or ''billing_manager''.


            Examples: ''admin.billing'', ''support.readonly'', ''developer.api'', ''manager.analytics''

            '
          example: support.readonly
        description:
          type: string
          maxLength: 512
          description: 'Provides comprehensive documentation of what this role encompasses and what access it grants.

            Include information about the intended use case, what permissions should be assigned, and any important considerations.

            This internal documentation helps team members understand role boundaries and security implications.

            Not visible to end users - designed for administration teams and access control audits.


            Consider documenting:

            - The role''s intended purpose and scope

            - What types of users should receive this role

            - What permissions are typically associated with it

            - Any security considerations or limitations

            - Related roles that might be used together

            '
          example: Provides read-only access for customer support representatives. Includes permissions to view user accounts,
            support tickets, and basic analytics. Does not include access to billing, admin functions, or data modification
            capabilities.
      additionalProperties: false
    V2PermissionsCreateRoleResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2PermissionsCreateRoleResponseData'
      additionalProperties: false
    V2PermissionsDeletePermissionRequestBody:
      type: object
      required:
      - permission
      properties:
        permission:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z][a-zA-Z0-9._-]*$
          description: 'Specifies which permission to permanently delete from your workspace.


            This can be a permission ID or a permission slug.


            WARNING: Deleting a permission has immediate and irreversible consequences:

            - All API keys with this permission will lose that access immediately

            - All roles containing this permission will have it removed

            - Any verification requests checking for this permission will fail

            - This action cannot be undone


            Before deletion, ensure you:

            - Have updated any keys or roles that depend on this permission

            - Have migrated to alternative permissions if needed

            - Have notified affected users about the access changes

            '
          example: perm_1234567890abcdef
      additionalProperties: false
    V2PermissionsDeletePermissionResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/EmptyResponse'
      additionalProperties: false
    V2PermissionsDeleteRoleRequestBody:
      type: object
      required:
      - role
      properties:
        role:
          type: string
          pattern: ^[a-zA-Z0-9_:\-\.\*]+$
          minLength: 3
          maxLength: 255
          description: 'Unique identifier of the role to permanently delete from your workspace.

            Must either be a valid role ID that begins with ''role_'' or the given role name and exists within your workspace.


            WARNING: Deletion is immediate and irreversible with significant consequences:

            - All API keys assigned this role will lose the associated permissions

            - Access to resources protected by this role''s permissions will be denied

            - Any authorization logic depending on this role will start failing

            - Historical analytics referencing this role remain intact


            Before deletion, ensure:

            - You''ve updated any dependent authorization logic or code

            - You''ve migrated any keys to use alternative roles or direct permissions

            - You''ve notified relevant team members of the access changes

            '
          example: role_dns_manager
      additionalProperties: false
    V2PermissionsDeleteRoleResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/EmptyResponse'
      additionalProperties: false
    V2PermissionsGetPermissionRequestBody:
      type: object
      required:
      - permission
      properties:
        permission:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z][a-zA-Z0-9._-]*$
          description: 'The unique identifier of the permission to retrieve. Must be a valid permission ID that begins with
            ''perm_'' and exists within your workspace.

            '
          example: perm_1234567890abcdef
      additionalProperties: false
    V2PermissionsGetPermissionResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/Permission'
      additionalProperties: false
    V2PermissionsGetRoleRequestBody:
      type: object
      required:
      - role
      properties:
        role:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_:\-\.\*]+$
          description: 'Unique identifier of the role to permanently delete from your workspace.

            Must either be a valid role ID that begins with ''role_'' or the given role name and exists within your workspace.


            Use this endpoint to verify role details, check its current permissions, or retrieve metadata.

            Returns complete role information including all assigned permissions for comprehensive access review.

            '
          example: role_1234567890abcdef
      additionalProperties: false
    V2PermissionsGetRoleResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/Role'
      additionalProperties: false
    V2PermissionsListPermissionsRequestBody:
      type: object
      properties:
        cursor:
          type: string
          maxLength: 1024
          description: 'Pagination cursor from a previous response to fetch the next page of permissions.

            Include this value when you need to retrieve additional permissions beyond the initial response.

            Each response containing more results than the requested limit includes a cursor for subsequent pages.


            Leave empty or omit this field to start from the beginning of the permission list.

            Cursors are temporary and may expire - always handle cases where a cursor becomes invalid.

            '
          example: eyJrZXkiOiJwZXJtXzEyMzQifQ==
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
          description: Maximum number of permissions to return in a single response.
          example: 50
      additionalProperties: false
    V2PermissionsListPermissionsResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2PermissionsListPermissionsResponseData'
        pagination:
          $ref: '#/components/schemas/Pagination'
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      additionalProperties: false
    V2PermissionsListRolesRequestBody:
      type: object
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
          description: 'Maximum number of roles to return in a single response.

            Use smaller values for faster response times and better UI performance.

            Use larger values when you need to process many roles efficiently.

            Results exceeding this limit will be paginated with a cursor for continuation.

            '
          example: 50
        cursor:
          type: string
          maxLength: 1024
          description: 'Pagination cursor from a previous response to fetch the next page of roles.

            Include this when you need to retrieve additional roles beyond the first page.

            Each response containing more results will include a cursor value that can be used here.

            Leave empty or omit this field to start from the beginning of the role list.

            '
          example: eyJrZXkiOiJyb2xlXzEyMzQifQ==
      additionalProperties: false
    V2PermissionsListRolesResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2PermissionsListRolesResponseData'
        pagination:
          $ref: '#/components/schemas/Pagination'
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      additionalProperties: false
    V2RatelimitDeleteOverrideRequestBody:
      description: 'Deletes an existing rate limit override. This permanently removes a custom rate limit rule, reverting
        affected identifiers back to the default rate limits for the namespace.


        Use this endpoint when you need to:

        - Remove special rate limit rules that are no longer needed

        - Reset entities back to standard rate limits

        - Clean up temporary overrides

        - Remove outdated tiering or custom limit rules

        - Fix misconfigured overrides


        Once deleted, the override cannot be recovered, and the operation takes effect immediately.'
      additionalProperties: false
      properties:
        namespace:
          description: The id or name of the namespace containing the override.
          type: string
          minLength: 1
          maxLength: 255
        identifier:
          description: 'The exact identifier pattern of the override to delete. This must match exactly as it was specified
            when creating the override.


            Important notes:

            - This is case-sensitive and must match exactly

            - Include any wildcards (*) that were part of the original pattern

            - For example, if the override was created for ''premium_*'', you must use ''premium_*'' here, not a specific
            ID


            After deletion, any identifiers previously affected by this override will immediately revert to using the default
            rate limit for the namespace.'
          type: string
          minLength: 1
          maxLength: 255
      required:
      - namespace
      - identifier
      type: object
    V2RatelimitDeleteOverrideResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2RatelimitDeleteOverrideResponseData'
    V2RatelimitGetOverrideRequestBody:
      description: 'Gets the configuration of an existing rate limit override. Use this to retrieve details about custom rate
        limit rules that have been created for specific identifiers within a namespace.


        This endpoint is useful for:

        - Verifying override configurations

        - Checking current limits for specific entities

        - Auditing rate limit policies

        - Debugging rate limiting behavior

        - Retrieving override settings for modification'
      additionalProperties: false
      properties:
        namespace:
          description: The id or name of the namespace containing the override.
          type: string
          minLength: 1
          maxLength: 255
        identifier:
          description: 'The exact identifier pattern for the override you want to retrieve. This must match exactly as it
            was specified when creating the override.


            Important notes:

            - This is case-sensitive and must match exactly

            - Include any wildcards (*) that were part of the original pattern

            - For example, if the override was created for ''premium_*'', you must use ''premium_*'' here, not a specific
            ID like ''premium_user1''


            This field is used to look up the specific override configuration for this pattern.'
          type: string
          minLength: 1
          maxLength: 255
      required:
      - namespace
      - identifier
      type: object
    V2RatelimitGetOverrideResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/RatelimitOverride'
    V2RatelimitLimitRequestBody:
      additionalProperties: false
      properties:
        namespace:
          type: string
          minLength: 1
          maxLength: 255
          description: The id or name of the namespace.
          example: sms.sign_up
        cost:
          type: integer
          format: int64
          minimum: 0
          default: 1
          description: 'Sets how much of the rate limit quota this request consumes, enabling weighted rate limiting.

            Use higher values for resource-intensive operations and 0 for tracking without limiting.

            When accumulated cost exceeds the limit within the duration window, subsequent requests are rejected.

            Essential for implementing fair usage policies and preventing resource abuse through expensive operations.

            '
          example: 5
        duration:
          type: integer
          format: int64
          minimum: 1000
          maximum: 2592000000
          description: 'Sets the rate limit window duration in milliseconds after which the counter resets.

            Shorter durations enable faster recovery but may be less effective against sustained abuse.

            Common values include 60000 (1 minute), 3600000 (1 hour), and 86400000 (24 hours).

            Balance user experience with protection needs when choosing window sizes.

            '
          example: 60000
        identifier:
          type: string
          minLength: 1
          maxLength: 255
          description: 'Defines the scope of rate limiting by identifying the entity being limited.

            Use user IDs for per-user limits, IP addresses for anonymous limiting, or API key IDs for per-key limits.

            Accepts letters, numbers, underscores, dots, colons, slashes, and hyphens for flexible identifier formats.

            The same identifier can be used across different namespaces to apply multiple rate limit types.

            Choose identifiers that provide appropriate granularity for your rate limiting strategy.

            '
          example: user_12345
        limit:
          type: integer
          format: int64
          minimum: 1
          description: 'Sets the maximum operations allowed within the duration window before requests are rejected.

            When this limit is reached, subsequent requests fail with `RATE_LIMITED` until the window resets.

            Balance user experience with resource protection when setting limits for different user tiers.

            Consider system capacity, business requirements, and fair usage policies in limit determination.

            '
          example: 1000
      required:
      - namespace
      - identifier
      - limit
      - duration
      type: object
    V2RatelimitLimitResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2RatelimitLimitResponseData'
    GoneErrorResponse:
      type: object
      required:
      - meta
      - error
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          $ref: '#/components/schemas/BaseError'
      description: 'Error response when the requested resource has been soft-deleted and is no longer available. This occurs
        when:

        - The resource has been marked as deleted but still exists in the database

        - The resource is intentionally unavailable but could potentially be restored

        - The resource cannot be restored through the API or dashboard


        To resolve this error, contact support if you need the resource restored.'
    V2RatelimitListOverridesRequestBody:
      additionalProperties: false
      properties:
        namespace:
          description: The id or name of the rate limit namespace to list overrides for.
          type: string
          minLength: 1
          maxLength: 255
        cursor:
          description: Pagination cursor from a previous response. Include this when fetching subsequent pages of results.
            Each response containing more results than the requested limit will include a cursor value in the pagination object
            that can be used here.
          type: string
        limit:
          description: 'Maximum number of override entries to return in a single response. Use this to control response size
            and loading performance.


            - Lower values (10-20): Better for UI displays and faster response times

            - Higher values (50-100): Better for data exports or bulk operations

            - Default (10): Suitable for most dashboard views


            Results exceeding this limit will be paginated, with a cursor provided for fetching subsequent pages.'
          type: integer
          default: 10
          minimum: 1
          maximum: 100
      required:
      - namespace
      type: object
    V2RatelimitListOverridesResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2RatelimitListOverridesResponseData'
        pagination:
          $ref: '#/components/schemas/Pagination'
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
    V2RatelimitMultiLimitRequestBody:
      type: array
      description: Array of rate limit checks to perform
      minItems: 1
      maxItems: 100
      items:
        $ref: '#/components/schemas/V2RatelimitLimitRequestBody'
    V2RatelimitMultiLimitResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2RatelimitMultiLimitResponseData'
    V2RatelimitSetOverrideRequestBody:
      description: 'Sets a new or overwrites an existing rate limit override. Overrides allow you to apply special rate limit
        rules to specific identifiers, providing custom limits that differ from the default.


        Overrides are useful for:

        - Granting higher limits to premium users or trusted partners

        - Implementing stricter limits for suspicious or abusive users

        - Creating tiered access levels with different quotas

        - Implementing temporary rate limit adjustments

        - Prioritizing important clients with higher limits'
      additionalProperties: false
      properties:
        namespace:
          description: The ID or name of the rate limit namespace.
          type: string
          minLength: 1
          maxLength: 255
        duration:
          description: 'The duration in milliseconds for the rate limit window. This defines how long the rate limit counter
            accumulates before resetting to zero.


            Considerations:

            - This can differ from the default duration for the namespace

            - Longer durations create stricter limits that take longer to reset

            - Shorter durations allow more frequent bursts of activity

            - Common values: 60000 (1 minute), 3600000 (1 hour), 86400000 (1 day)'
          format: int64
          type: integer
          minimum: 1000
        identifier:
          description: 'Identifier of the entity receiving this custom rate limit. This can be:


            - A specific user ID for individual custom limits

            - An IP address for location-based rules

            - An email domain for organization-wide policies

            - Any other string that identifies the target entity


            Wildcards (*) can be used to create pattern-matching rules that apply to multiple identifiers. For example:

            - ''premium_*'' would match all identifiers starting with ''premium_''

            - ''*_admin'' would match all identifiers ending with ''_admin''

            - ''*suspicious*'' would match any identifier containing ''suspicious''


            More detailed information on wildcard pattern rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules'
          type: string
          minLength: 1
          maxLength: 255
        limit:
          description: 'The maximum number of requests allowed for this override. This defines the custom quota for the specified
            identifier(s).


            Special values:

            - Higher than default: For premium or trusted entities

            - Lower than default: For suspicious or abusive entities

            - 0: To completely block access (useful for ban implementation)


            This limit entirely replaces the default limit for matching identifiers.'
          format: int64
          type: integer
          minimum: 0
      required:
      - namespace
      - identifier
      - limit
      - duration
      type: object
    V2RatelimitSetOverrideResponseBody:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          $ref: '#/components/schemas/V2RatelimitSetOverrideResponseData'
    Meta:
      type: object
      required:
      - requestId
      properties:
        requestId:
          description: A unique id for this request. Always include this ID when contacting support about a specific API request.
            This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to
            provide faster assistance.
          example: req_123
          type: string
      additionalProperties: false
      description: Metadata object included in every API response. This provides context about the request and is essential
        for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting
        issues with the Unkey support team.
    V2AnalyticsGetVerificationsResponseData:
      type: array
      description: Array of verification rows returned by the query. Fields vary based on the SQL SELECT clause.
      items:
        type: object
        additionalProperties: true
        description: Dynamic row with fields determined by the query. Can include any combination of fields like time, outcome,
          count, key_id, etc.
      example:
      - outcome: VALID
        count: 1234
        time: 1696118400000
      - outcome: RATE_LIMITED
        count: 56
        time: 1696118400000
    BadRequestErrorDetails:
      allOf:
      - $ref: '#/components/schemas/BaseError'
      - type: object
        properties:
          errors:
            description: List of individual validation errors that occurred in the request. Each error provides specific details
              about what failed validation, where the error occurred in the request, and suggestions for fixing it. This granular
              information helps developers quickly identify and resolve multiple issues in a single request without having
              to make repeated API calls.
            items:
              $ref: '#/components/schemas/ValidationError'
            type: array
        required:
        - errors
      description: Extended error details specifically for bad request (400) errors. This builds on the BaseError structure
        by adding an array of individual validation errors, making it easy to identify and fix multiple issues at once.
    BaseError:
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem. This provides detailed information
            about what went wrong and potential remediation steps. The message is intended to be helpful for developers troubleshooting
            the issue.
          example: Property foo is required but is missing.
          type: string
        status:
          description: HTTP status code that corresponds to this error. This will match the status code in the HTTP response.
            Common codes include `400` (Bad Request), `401` (Unauthorized), `403` (Forbidden), `404` (Not Found), `409` (Conflict),
            and `500` (Internal Server Error).
          example: 404
          format: int
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This remains constant from occurrence to occurrence
            of the same problem and should be used for programmatic handling.
          example: Not Found
          type: string
        type:
          description: A URI reference that identifies the problem type. This provides a stable identifier for the error that
            can be used for documentation lookups and programmatic error handling. When followed, this URI should provide
            human-readable documentation for the problem type.
          example: https://unkey.com/docs/errors/unkey/resource/not_found
          type: string
      required:
      - title
      - detail
      - status
      - type
      type: object
      additionalProperties: false
      description: Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way
        to carry machine-readable details of errors in HTTP response content.
    ValidationError:
      additionalProperties: false
      properties:
        location:
          description: 'JSON path indicating exactly where in the request the error occurred. This helps pinpoint the problematic
            field or parameter. Examples include:

            - ''body.name'' (field in request body)

            - ''body.items[3].tags'' (nested array element)

            - ''path.apiId'' (path parameter)

            - ''query.limit'' (query parameter)

            Use this location to identify exactly which part of your request needs correction.'
          type: string
          example: body.permissions[0].name
        message:
          description: Detailed error message explaining what validation rule was violated. This provides specific information
            about why the field or parameter was rejected, such as format errors, invalid values, or constraint violations.
          type: string
          example: Must be at least 3 characters long
        fix:
          description: A human-readable suggestion describing how to fix the error. This provides practical guidance on what
            changes would satisfy the validation requirements. Not all validation errors include fix suggestions, but when
            present, they offer specific remediation advice.
          type: string
          example: Ensure the name uses only alphanumeric characters, underscores, and hyphens
      required:
      - location
      - message
      type: object
      description: Individual validation error details. Each validation error provides precise information about what failed,
        where it failed, and how to fix it, enabling efficient error resolution.
    V2ApisCreateApiResponseData:
      type: object
      properties:
        apiId:
          type: string
          minLength: 8
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'The unique identifier assigned to the newly created API.

            Use this ID for all subsequent operations including key creation, verification, and API management.

            Always begins with ''api_'' followed by a unique alphanumeric sequence.


            Store this ID securely as it''s required when:

            - Creating API keys within this namespace

            - Verifying keys associated with this API

            - Managing API settings and metadata

            - Listing keys belonging to this API


            This identifier is permanent and cannot be changed after creation.

            '
          example: api_2cGKbMxRjIzhCxo1IdjH3a
      required:
      - apiId
      additionalProperties: false
    EmptyResponse:
      type: object
      additionalProperties: false
      description: Empty response object by design. A successful response indicates this operation was successfully executed.
    V2ApisGetApiResponseData:
      type: object
      properties:
        id:
          type: string
          minLength: 8
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'The unique identifier of this API within Unkey''s system.

            Used in all operations related to this API including key creation, verification, and management.

            Always begins with ''api_'' followed by alphanumeric characters and underscores.

            This identifier is permanent and never changes after API creation.

            '
          example: api_1234567890abcdef
        name:
          type: string
          minLength: 3
          maxLength: 255
          description: 'The internal name of this API as specified during creation.

            Used for organization and identification within your workspace.

            Helps distinguish between different environments, services, or access tiers.

            Not visible to end users - this is purely for administrative purposes.

            '
          example: payment-service-production
      required:
      - id
      - name
      additionalProperties: false
    V2ApisListKeysResponseData:
      type: array
      maxItems: 100
      items:
        $ref: '#/components/schemas/KeyResponseData'
      description: Array of API keys with complete configuration and metadata.
    Pagination:
      type: object
      properties:
        cursor:
          type: string
          minLength: 1
          maxLength: 1024
          description: 'Opaque pagination token for retrieving the next page of results.

            Include this exact value in the cursor field of subsequent requests.

            Cursors are temporary and may expire after extended periods.

            '
          example: eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ==
        hasMore:
          type: boolean
          description: 'Indicates whether additional results exist beyond this page.

            When true, use the cursor to fetch the next page.

            When false, you have reached the end of the result set.

            '
          example: true
      required:
      - hasMore
      additionalProperties: false
      description: Pagination metadata for list endpoints. Provides information necessary to traverse through large result
        sets efficiently using cursor-based pagination.
    KeyResponseData:
      type: object
      properties:
        keyId:
          type: string
          minLength: 8
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: Unique identifier for this key.
          example: key_1234567890abcdef
        start:
          type: string
          minLength: 1
          maxLength: 50
          description: First few characters of the key for identification.
          example: sk_test_abc123
        enabled:
          type: boolean
          description: Whether the key is enabled or disabled.
          example: true
        name:
          type: string
          maxLength: 255
          description: Human-readable name for this key.
          example: Production API Key
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        meta:
          type: object
          additionalProperties: true
          maxProperties: 100
          description: Custom metadata associated with this key.
          example: null
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        createdAt:
          type: integer
          format: int64
          minimum: 0
          maximum: 9223372036854776000
          description: Unix timestamp in milliseconds when key was created.
          example: 1701425400000
        updatedAt:
          type: integer
          format: int64
          minimum: 0
          maximum: 9223372036854776000
          description: Unix timestamp in milliseconds when key was last updated.
          example: 1701425400000
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        lastUsedAt:
          type: integer
          format: int64
          minimum: 0
          description: Unix timestamp in milliseconds when key was last used for verification. This is an approximated value,
            accurate to within 5 minutes.
          example: 1701425400000
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        expires:
          type: integer
          format: int64
          minimum: 0
          maximum: 9223372036854776000
          description: Unix timestamp in milliseconds when key expires (if set).
          example: 1735689600000
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        permissions:
          type: array
          items:
            type: string
            description: List of permission slugs granted to this key.
          example:
          - documents.read
          - documents.write
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        roles:
          type: array
          items:
            type: string
            description: List of roles assigned to this key.
          example:
          - editor
          - viewer
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        credits:
          $ref: '#/components/schemas/KeyCreditsData'
        identity:
          $ref: '#/components/schemas/Identity'
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        plaintext:
          type: string
          description: Decrypted key value (only when decrypt=true).
          example: sk_test_abc123def456
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        ratelimits:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/RatelimitResponse'
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      required:
      - keyId
      - start
      - createdAt
      - enabled
      additionalProperties: false
    KeyCreditsData:
      type: object
      description: Credit configuration and remaining balance for this key.
      properties:
        remaining:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 0
          maximum: 9223372036854776000
          description: Number of credits remaining (null for unlimited).
          example: 1000
        refill:
          $ref: '#/components/schemas/KeyCreditsRefill'
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      required:
      - remaining
      additionalProperties: false
    Identity:
      type: object
      properties:
        id:
          type: string
          description: Identity ID
        externalId:
          type: string
          description: External identity ID
        meta:
          type: object
          additionalProperties: true
          description: Identity metadata
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        ratelimits:
          type: array
          description: Identity ratelimits
          items:
            $ref: '#/components/schemas/RatelimitResponse'
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      required:
      - externalId
      - id
    RatelimitResponse:
      type: object
      properties:
        id:
          type: string
          minLength: 8
          maxLength: 255
          pattern: ^rl_[a-zA-Z0-9_]+$
          description: Unique identifier for this rate limit configuration.
          example: rl_1234567890abcdef
        name:
          type: string
          minLength: 1
          maxLength: 128
          description: Human-readable name for this rate limit.
          example: api_requests
        limit:
          type: integer
          format: int64
          minimum: 1
          maximum: 1000000
          description: Maximum requests allowed within the time window.
          example: 1000
        duration:
          type: integer
          format: int64
          minimum: 1000
          maximum: 2592000000
          description: Rate limit window duration in milliseconds.
          example: 3600000
        autoApply:
          type: boolean
          description: Whether this rate limit was automatically applied when verifying the key.
          example: true
      required:
      - id
      - name
      - limit
      - duration
      - autoApply
      additionalProperties: false
    KeyCreditsRefill:
      type: object
      description: Configuration for automatic credit refill behavior.
      properties:
        interval:
          type: string
          enum:
          - daily
          - monthly
          x-speakeasy-unknown-values: allow
          description: How often credits are automatically refilled.
          example: daily
        amount:
          type: integer
          format: int64
          minimum: 1
          maximum: 9223372036854776000
          description: Number of credits to add during each refill cycle.
          example: 1000
        refillDay:
          type: integer
          minimum: 1
          maximum: 31
          description: 'Day of the month for monthly refills (1-31).

            Only required when interval is ''monthly''.

            For days beyond the month''s length, refill occurs on the last day of the month.

            '
          example: 15
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      required:
      - interval
      - amount
      additionalProperties: false
    V2DeployGitCommit:
      type: object
      description: Optional git commit information
      properties:
        commitSha:
          type: string
          description: Git commit SHA
          example: a1b2c3d4e5f6
        commitMessage:
          type: string
          description: Git commit message
          example: 'feat: add new feature'
        authorHandle:
          type: string
          description: Git author handle/username
          example: johndoe
        authorAvatarUrl:
          type: string
          description: Git author avatar URL
          example: https://avatars.githubusercontent.com/u/123456
        timestamp:
          type: integer
          format: int64
          description: Commit timestamp in milliseconds
          example: 1704067200000
    V2DeployCreateDeploymentResponseData:
      type: object
      required:
      - deploymentId
      properties:
        deploymentId:
          type: string
          description: Unique deployment identifier
          example: d_abc123xyz
    V2DeployGetDeploymentResponseData:
      type: object
      required:
      - id
      - status
      properties:
        id:
          type: string
          description: Unique deployment identifier
          example: d_abc123xyz
        status:
          type: string
          description: Current deployment status
          enum:
          - UNSPECIFIED
          - PENDING
          - STARTING
          - BUILDING
          - DEPLOYING
          - NETWORK
          - FINALIZING
          - READY
          - FAILED
          - SKIPPED
          - AWAITING_APPROVAL
          - STOPPED
          - SUPERSEDED
          - CANCELLED
          example: READY
          x-speakeasy-unknown-values: allow
        errorMessage:
          type: string
          description: Error message if deployment failed
          example: 'Failed to pull image: authentication required'
        hostnames:
          type: array
          items:
            type: string
          description: Hostnames associated with this deployment
          example:
          - app.example.com
          - api.example.com
        steps:
          type: array
          items:
            $ref: '#/components/schemas/V2DeployDeploymentStep'
          description: Deployment steps with status and messages
    V2DeployDeploymentStep:
      type: object
      properties:
        status:
          type: string
          description: Step status
          example: completed
        message:
          type: string
          description: Step message
          example: Image pulled successfully
        errorMessage:
          type: string
          description: Error message if step failed
          example: Connection timeout
        createdAt:
          type: integer
          format: int64
          description: Unix timestamp in milliseconds
          example: 1704067200000
    RatelimitRequest:
      type: object
      required:
      - name
      - limit
      - duration
      - autoApply
      properties:
        name:
          description: 'The name of this rate limit. This name is used to identify which limit to check during key verification.


            Best practices for limit names:

            - Use descriptive, semantic names like ''api_requests'', ''heavy_operations'', or ''downloads''

            - Be consistent with naming conventions across your application

            - Create separate limits for different resource types or operation costs

            - Consider using namespaced names for better organization (e.g., ''files.downloads'', ''compute.training'')


            You will reference this exact name when verifying keys to check against this specific limit.'
          type: string
          example: api
          minLength: 3
          maxLength: 128
        limit:
          description: 'The maximum number of operations allowed within the specified time window.


            When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets.
            The limit should reflect:

            - Your infrastructure capacity and scaling limitations

            - Fair usage expectations for your service

            - Different tier levels for various user types

            - The relative cost of the operations being limited


            Higher values allow more frequent access but may impact service performance.'
          type: integer
          format: int64
          minimum: 1
        duration:
          description: 'The duration for each ratelimit window in milliseconds.


            This controls how long the rate limit counter accumulates before resetting. Common values include:

            - 1000 (1 second): For strict per-second limits on high-frequency operations

            - 60000 (1 minute): For moderate API usage control

            - 3600000 (1 hour): For less frequent but costly operations

            - 86400000 (24 hours): For daily quotas


            Shorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent
            usage patterns but take longer to reset after limit exhaustion.'
          type: integer
          format: int64
          minimum: 1000
        autoApply:
          description: Whether this ratelimit should be automatically applied when verifying a key.
          type: boolean
          default: false
    V2IdentitiesCreateIdentityResponseData:
      type: object
      properties:
        identityId:
          type: string
          description: The unique identifier of the created identity.
      required:
      - identityId
    V2IdentitiesListIdentitiesResponseData:
      type: array
      items:
        $ref: '#/components/schemas/Identity'
      description: List of identities matching the specified criteria.
    V2KeysAddPermissionsResponseData:
      type: array
      description: 'Complete list of all permissions directly assigned to the key (including both newly added permissions
        and those that were already assigned).


        This response includes:

        - All direct permissions assigned to the key (both pre-existing and newly added)

        - Both the permission ID and name for each permission


        Important notes:

        - This list does NOT include permissions granted through roles

        - For a complete permission picture, use `/v2/keys.getKey` instead

        - An empty array indicates the key has no direct permissions assigned'
      items:
        $ref: '#/components/schemas/Permission'
    Permission:
      type: object
      properties:
        id:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'The unique identifier for this permission within Unkey''s system.

            Generated automatically when the permission is created and used to reference this permission in API operations.

            Always begins with ''perm_'' followed by alphanumeric characters and underscores.

            '
          example: perm_1234567890abcdef
        name:
          type: string
          minLength: 1
          maxLength: 512
          description: 'The human-readable name for this permission that describes its purpose.

            Should be descriptive enough for developers to understand what access it grants.

            Use clear, semantic names that reflect the resources or actions being permitted.

            Names must be unique within your workspace to avoid confusion and conflicts.

            '
          example: users.read
        slug:
          pattern: ^[a-zA-Z0-9_:\-\.\*]+$
          type: string
          minLength: 1
          maxLength: 512
          description: The unique URL-safe identifier for this permission.
          example: users-read
        description:
          type: string
          maxLength: 512
          description: 'Optional detailed explanation of what this permission grants access to.

            Helps team members understand the scope and implications of granting this permission.

            Include information about what resources can be accessed and what actions can be performed.

            Not visible to end users - this is for internal documentation and team clarity.

            '
          example: Allows reading user profile information and account details
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      required:
      - id
      - name
      - slug
    V2KeysAddRolesResponseData:
      type: array
      description: 'Complete list of all roles directly assigned to the key after the operation completes.


        The response includes:

        - All roles now assigned to the key (both pre-existing and newly added)

        - Both ID and name of each role for easy reference


        Important notes:

        - The response shows the complete current state after the addition

        - An empty array means the key has no roles assigned (unlikely after an add operation)

        - This only shows direct role assignments, not inherited or nested roles

        - Role permissions are not expanded in this response - use keys.getKey for full details'
      items:
        $ref: '#/components/schemas/Role'
    Role:
      type: object
      properties:
        id:
          type: string
          description: 'The unique identifier for this role within Unkey''s system.

            Generated automatically when the role is created and used to reference this role in API operations.

            Always begins with ''role_'' followed by alphanumeric characters and underscores.

            '
          example: role_1234567890abcdef
        name:
          type: string
          description: 'The human-readable name for this role that describes its function.

            Should be descriptive enough for administrators to understand what access this role provides.

            Use clear, semantic names that reflect the job function or responsibility level.

            Names must be unique within your workspace to avoid confusion during role assignment.

            '
          example: support.readonly
        description:
          type: string
          description: 'Optional detailed explanation of what this role encompasses and what access it provides.

            Helps team members understand the role''s scope, intended use cases, and security implications.

            Include information about what types of users should receive this role and what they can accomplish.

            Not visible to end users - this is for internal documentation and access control audits.

            '
          example: Provides read-only access for customer support representatives to view user accounts and support tickets
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
          maxItems: 100
          description: 'Complete list of permissions currently assigned to this role.

            Each permission grants specific access rights that will be inherited by any keys or users assigned this role.

            Use this list to understand the full scope of access provided by this role.

            Permissions can be added or removed from roles without affecting the role''s identity or other properties.

            Empty array indicates a role with no permissions currently assigned.

            '
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      required:
      - id
      - name
      additionalProperties: false
    V2KeysCreateKeyResponseData:
      type: object
      properties:
        keyId:
          type: string
          description: The unique identifier for this key in Unkey's system. This is NOT the actual API key, but a reference
            ID used for management operations like updating or deleting the key. Store this ID in your database to reference
            the key later. This ID is not sensitive and can be logged or displayed in dashboards.
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        key:
          type: string
          description: 'The full generated API key that should be securely provided to your user.

            SECURITY WARNING: This is the only time you''ll receive the complete key - Unkey only stores a securely hashed
            version. Never log or store this value in your own systems; provide it directly to your end user via secure channels.
            After this API call completes, this value cannot be retrieved again (unless created with `recoverable=true`).'
          example: prod_2cGKbMxRjIzhCxo1IdjH3arELti7Sdyc8w6XYbvtcyuBowPT
      required:
      - keyId
      - key
    V2KeysMigrateKeyData:
      type: object
      properties:
        hash:
          type: string
          minLength: 3
          description: The current hash of the key on your side
          example: your_already_hashed_key
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: 'Sets a human-readable identifier for internal organization and dashboard display.

            Never exposed to end users, only visible in management interfaces and API responses.

            Avoid generic names like "API Key" when managing multiple keys for the same user or service.

            '
          example: Payment Service Production Key
        externalId:
          type: string
          minLength: 1
          maxLength: 255
          description: 'Links this key to a user or entity in your system using your own identifier.

            Returned during verification to identify the key owner without additional database lookups.

            Essential for user-specific analytics, billing, and multi-tenant key management.

            Use your primary user ID, organization ID, or tenant ID for best results.

            Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.

            '
          example: user_1234abcd
        meta:
          type: object
          additionalProperties: true
          maxProperties: 100
          description: 'Stores arbitrary JSON metadata returned during key verification for contextual information.

            Eliminates additional database lookups during verification, improving performance for stateless services.

            Avoid storing sensitive data here as it''s returned in verification responses.

            Large metadata objects increase verification latency and should stay under 10KB total size.

            '
          example:
            plan: enterprise
            featureFlags:
              betaAccess: true
              concurrentConnections: 10
            customerName: Acme Corp
            billing:
              tier: premium
              renewal: '2024-12-31'
        roles:
          type: array
          maxItems: 100
          items:
            type: string
            minLength: 1
            maxLength: 100
          description: 'Assigns existing roles to this key for permission management through role-based access control.

            Roles must already exist in your workspace before assignment.

            During verification, all permissions from assigned roles are checked against requested permissions.

            Roles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.

            '
          example:
          - api_admin
          - billing_reader
        permissions:
          type: array
          maxItems: 1000
          items:
            type: string
            minLength: 1
            maxLength: 100
          description: 'Grants specific permissions directly to this key without requiring role membership.

            Wildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.

            Direct permissions supplement any permissions inherited from assigned roles.

            '
          example:
          - documents.read
          - documents.write
          - settings.view
        expires:
          type: integer
          format: int64
          minimum: 0
          maximum: 4102444800000
          description: 'Sets when this key automatically expires as a Unix timestamp in milliseconds.

            Verification fails with code=EXPIRED immediately after this time passes.

            Omitting this field creates a permanent key that never expires.


            Avoid setting timestamps in the past as they immediately invalidate the key.

            Keys expire based on server time, not client time, which prevents timezone-related issues.

            Essential for trial periods, temporary access, and security compliance requiring key rotation.

            '
        enabled:
          type: boolean
          default: true
          description: 'Controls whether the key is active immediately upon creation.

            When set to `false`, the key exists but all verification attempts fail with `code=DISABLED`.

            Useful for pre-creating keys that will be activated later or for keys requiring manual approval.

            Most keys should be created with `enabled=true` for immediate use.

            '
          example: true
        credits:
          $ref: '#/components/schemas/KeyCreditsData'
          description: 'Controls usage-based limits through credit consumption with optional automatic refills.

            Unlike rate limits which control frequency, credits control total usage with global consistency.

            Essential for implementing usage-based pricing, subscription tiers, and hard usage quotas.

            Omitting this field creates unlimited usage, while setting null is not allowed during creation.

            '
        ratelimits:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/RatelimitRequest'
          description: 'Defines time-based rate limits that protect against abuse by controlling request frequency.

            Unlike credits which track total usage, rate limits reset automatically after each window expires.

            Multiple rate limits can control different operation types with separate thresholds and windows.

            Essential for preventing API abuse while maintaining good performance for legitimate usage.

            '
          example:
          - name: requests
            limit: 100
            duration: 60000
            autoApply: true
          - name: heavy_operations
            limit: 10
            duration: 3600000
            autoApply: false
      additionalProperties: false
      required:
      - hash
    V2KeysMigrateKeysResponseData:
      type: object
      required:
      - migrated
      - failed
      properties:
        migrated:
          type: array
          description: Successfully migrated keys with their hash and generated keyId
          items:
            $ref: '#/components/schemas/V2KeysMigrateKeysMigration'
        failed:
          type: array
          description: Hashes that could not be migrated (e.g., already exist in the system)
          items:
            type: string
            description: The hash that failed to migrate
            example: sha256_ghi789jkl012
    V2KeysMigrateKeysMigration:
      type: object
      required:
      - hash
      - keyId
      properties:
        hash:
          type: string
          description: The hash provided in the migration request
          example: sha256_abc123def456
        keyId:
          type: string
          description: The unique identifier for this key in Unkey's system. This is NOT the actual API key, but a reference
            ID used for management operations like updating or deleting the key. Store this ID in your database to reference
            the key later. This ID is not sensitive and can be logged or displayed in dashboards.
          example: key_2cGKbMxRyIzhCxo1Idjz8q
    V2KeysRemovePermissionsResponseData:
      type: array
      description: 'Complete list of all permissions directly assigned to the key after the removal operation (remaining permissions
        only).


        Notes:

        - This list does NOT include permissions granted through roles

        - For a complete permission picture, use `/v2/keys.getKey` instead

        - An empty array indicates the key has no direct permissions assigned

        - Any cached versions of the key are immediately invalidated to ensure consistency

        - Changes to permissions take effect within seconds for new verifications'
      items:
        $ref: '#/components/schemas/Permission'
    V2KeysRemoveRolesResponseData:
      type: array
      description: 'Complete list of all roles directly assigned to the key after the removal operation completes.


        The response includes:

        - The remaining roles still assigned to the key (after removing the specified roles)

        - Both ID and name for each role for easy reference


        Important notes:

        - The response reflects the current state after the removal operation

        - An empty array indicates the key now has no roles assigned

        - This only shows direct role assignments

        - Role permissions are not expanded in this response - use keys.getKey for full details

        - Changes take effect immediately for new verifications but cached sessions may retain old permissions briefly'
      items:
        $ref: '#/components/schemas/Role'
    V2KeysRerollKeyResponseData:
      type: object
      properties:
        keyId:
          type: string
          description: 'The unique identifier for the newly created key.


            This is NOT the actual API key token, but a reference ID for management operations.

            Store this ID to:

            - Update or revoke the key later

            - Track the key in your database

            - Display in admin dashboards (safe to log)


            Note: This is a new ID - the original key retains its own ID.

            '
          example: key_2cGKbMxRyIzhCxo1Idjz8q
        key:
          type: string
          description: 'The newly generated API key token (the actual secret that authenticates requests).


            **SECURITY CRITICAL:**

            - This is the only time you''ll receive the complete key

            - Unkey stores only a hashed version (unless the original key was created with `recoverable=true`)

            - Never log, store, or expose this value in your systems

            - Transmit directly to the end user via secure channels only

            - If lost and not recoverable, you must reroll or create a new key


            The key format follows: `[prefix]_[random_bytes]`

            - Prefix is extracted from the original key or uses API default

            - Random bytes follow API configuration (default: 16 bytes)


            This is NOT the keyId - it''s the actual secret token used for authentication.

            '
          example: prod_2cGKbMxRjIzhCxo1IdjH3arELti7Sdyc8w6XYbvtcyuBowPT
      required:
      - keyId
      - key
    V2KeysSetPermissionsResponseData:
      type: array
      description: 'Complete list of all permissions now directly assigned to the key after the set operation has completed.


        The response includes:

        - The comprehensive, updated set of direct permissions (reflecting the complete replacement)

        - Both ID and name for each permission for easy reference


        Important notes:

        - This only shows direct permissions, not those granted through roles

        - An empty array means the key has no direct permissions assigned

        - For a complete permission picture including roles, use keys.getKey instead'
      items:
        $ref: '#/components/schemas/Permission'
    V2KeysSetRolesResponseData:
      type: array
      description: 'Complete list of all roles now directly assigned to the key after the set operation has completed.


        The response includes:

        - The comprehensive, updated set of roles (reflecting the complete replacement)

        - Both ID and name for each role for easy reference


        Important notes:

        - This response shows the final state after the complete replacement

        - If you provided an empty array in the request, this will also be empty

        - This only shows direct role assignments on the key

        - Role permissions are not expanded in this response - use keys.getKey for complete details

        - An empty array indicates the key now has no roles assigned at all'
      items:
        $ref: '#/components/schemas/Role'
    UpdateKeyCreditsData:
      type:
      - object
      - 'null'
      description: Credit configuration and remaining balance for this key.
      properties:
        remaining:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 0
          maximum: 9223372036854776000
          description: Number of credits remaining (null for unlimited). This also clears the refilling schedule.
          example: 1000
        refill:
          $ref: '#/components/schemas/UpdateKeyCreditsRefill'
      additionalProperties: false
    UpdateKeyCreditsRefill:
      type:
      - object
      - 'null'
      description: Configuration for automatic credit refill behavior.
      properties:
        interval:
          type: string
          enum:
          - daily
          - monthly
          x-speakeasy-unknown-values: allow
          description: How often credits are automatically refilled.
          example: daily
        amount:
          type: integer
          format: int64
          minimum: 1
          maximum: 9223372036854776000
          description: Number of credits to add during each refill cycle.
          example: 1000
        refillDay:
          type: integer
          minimum: 1
          maximum: 31
          description: 'Day of the month for monthly refills (1-31).

            Only required when interval is ''monthly''.

            For days beyond the month''s length, refill occurs on the last day of the month.

            '
          example: 15
      required:
      - interval
      - amount
      additionalProperties: false
    KeysVerifyKeyCredits:
      type: object
      required:
      - cost
      properties:
        cost:
          type: integer
          format: int64
          minimum: 0
          maximum: 1000000000000
          description: 'Sets how many credits to deduct for this verification request.

            Use 0 for read-only operations or free tier access, higher values for premium features.

            Credits are deducted after all security checks pass.

            Essential for implementing usage-based pricing with different operation costs.

            '
          example: 5
      additionalProperties: false
      description: 'Controls credit consumption for usage-based billing and quota enforcement.

        Omitting this field uses the default cost of 1 credit per verification.

        Credits provide globally consistent usage tracking, essential for paid APIs with strict quotas.

        '
    KeysVerifyKeyRatelimit:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 255
          description: References an existing ratelimit by its name. Key Ratelimits will take precedence over identifier-based
            limits.
          example: tokens
        cost:
          type: integer
          minimum: 0
          default: 1
          description: Optionally override how expensive this operation is and how many tokens are deducted from the current
            limit.
          example: 2
        limit:
          type: integer
          minimum: 0
          description: Optionally override the maximum number of requests allowed within the specified interval.
          example: 50
        duration:
          type: integer
          minimum: 0
          description: Optionally override the duration of the rate limit window duration.
          example: 600000
    V2KeysVerifyKeyResponseData:
      type: object
      additionalProperties: false
      properties:
        valid:
          type: boolean
          description: 'The primary verification result. If true, the key is valid

            and can be used. If false, check the ''code'' field to understand why verification

            failed. Your application should always check this field first before proceeding.

            '
        code:
          type: string
          enum:
          - VALID
          - NOT_FOUND
          - FORBIDDEN
          - INSUFFICIENT_PERMISSIONS
          - USAGE_EXCEEDED
          - RATE_LIMITED
          - DISABLED
          - EXPIRED
          x-speakeasy-unknown-values: allow
          description: 'A machine-readable code indicating the verification status

            or failure reason. Values: `VALID` (key is valid and passed all checks), `NOT_FOUND` (key doesn''t

            exist or belongs to wrong API), `FORBIDDEN` (key lacks required permissions), `INSUFFICIENT_PERMISSIONS`

            (key lacks specific required permissions for this request), `USAGE_EXCEEDED` (key has no remaining credits), `RATE_LIMITED`
            (key exceeded rate limits), `DISABLED` (key was explicitly disabled),

            `EXPIRED` (key has passed its expiration date).

            '
        keyId:
          type: string
          description: 'The unique identifier of the verified key in Unkey''s system.

            Use this ID for operations like updating or revoking the key. This field

            is returned for both valid and invalid keys (except when `code=NOT_FOUND`).

            '
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        name:
          type: string
          description: 'The human-readable name assigned to this key during creation.

            This is useful for displaying in logs or admin interfaces to identify

            the key''s purpose.

            '
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        meta:
          type: object
          additionalProperties: true
          description: 'Custom metadata associated with the key. This can include any

            JSON-serializable data you stored with the key during creation or updates,

            such as plan information, feature flags, or user details. Use this to

            avoid additional database lookups for contextual information needed during

            API calls.

            '
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        expires:
          type: integer
          format: int64
          description: 'Unix timestamp (in milliseconds) when the key will expire.

            If omitted, the key has no expiration. You can use this to

            warn users about upcoming expirations or to understand the validity period.

            '
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        credits:
          type: integer
          format: int64
          description: 'The number of requests/credits remaining for this key. If omitted,

            the key has unlimited usage. This value decreases with

            each verification (based on the ''cost'' parameter) unless explicit credit

            refills are configured.

            '
        enabled:
          type: boolean
          description: 'Indicates if the key is currently enabled. Disabled keys will

            always fail verification with `code=DISABLED`. This is useful for implementing

            temporary suspensions without deleting the key.

            '
        permissions:
          type: array
          items:
            type: string
          description: 'A list of all permission names assigned to this key, either

            directly or through roles. These permissions determine what actions the

            key can perform. Only returned when permissions were checked during verification

            or when the key fails with `code=FORBIDDEN`.

            '
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        roles:
          type: array
          items:
            type: string
          description: 'A list of all role names assigned to this key. Roles are collections

            of permissions that grant access to specific functionality. Only returned

            when permissions were checked during verification.

            '
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        identity:
          $ref: '#/components/schemas/Identity'
          description: 'Information about the identity associated with this key. Identities

            allow multiple keys to share resources (like rate limits) and represent

            the same user or entity across different applications or devices.

            '
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
        ratelimits:
          type: array
          items:
            $ref: '#/components/schemas/VerifyKeyRatelimitData'
            description: The ratelimits that got checked
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      required:
      - valid
      - code
    VerifyKeyRatelimitData:
      type: object
      properties:
        exceeded:
          type: boolean
          description: Whether the rate limit was exceeded.
        id:
          type: string
          minLength: 8
          maxLength: 255
          pattern: ^rl_[a-zA-Z0-9_]+$
          description: Unique identifier for this rate limit configuration.
          example: rl_1234567890abcdef
        name:
          type: string
          minLength: 1
          maxLength: 128
          description: Human-readable name for this rate limit.
          example: api_requests
        limit:
          type: integer
          format: int64
          minimum: 1
          maximum: 1000000
          description: Maximum requests allowed within the time window.
          example: 1000
        duration:
          type: integer
          format: int64
          minimum: 1000
          maximum: 2592000000
          description: Rate limit window duration in milliseconds.
          example: 3600000
        reset:
          type: integer
          format: int64
          minimum: 1000
          maximum: 2592000000
          description: Rate limit reset duration in milliseconds.
          example: 3600000
        remaining:
          type: integer
          format: int64
          minimum: 0
          maximum: 1000000
          description: Rate limit remaining requests within the time window.
          example: 999
        autoApply:
          type: boolean
          description: 'Whether this rate limit should be automatically applied when verifying keys.

            When true, we will automatically apply this limit during verification without it being explicitly listed.

            '
          example: true
      required:
      - id
      - exceeded
      - name
      - limit
      - duration
      - reset
      - remaining
      - autoApply
      additionalProperties: false
    V2LivenessResponseData:
      type: object
      properties:
        message:
          description: Status message indicating the health of the service. A value of 'OK' indicates that the service is
            functioning properly and ready to accept requests. Any other value indicates a potential issue with the service
            health.
          example: OK
          type: string
      required:
      - message
      description: Response data for the liveness check endpoint. This provides a simple indication of whether the Unkey API
        service is running and able to process requests. Monitoring systems can use this endpoint to track service availability
        and trigger alerts if the service becomes unhealthy.
    V2PermissionsCreatePermissionResponseData:
      type: object
      properties:
        permissionId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'The unique identifier assigned to the newly created permission.

            Use this ID to reference the permission in role assignments, key operations, and other API calls.

            Always begins with ''perm_'' followed by a unique alphanumeric sequence.

            Store this ID if you need to manage or reference this permission in future operations.

            '
          example: perm_1234567890abcdef
      required:
      - permissionId
      additionalProperties: false
    V2PermissionsCreateRoleResponseData:
      type: object
      properties:
        roleId:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9_]+$
          description: 'The unique identifier assigned to the newly created role.

            Use this ID to reference the role in permission assignments, key operations, and role management calls.

            Always begins with ''role_'' followed by a unique alphanumeric sequence.

            Store this ID if you need to manage, modify, or assign this role in future operations.

            '
          example: role_1234567890abcdef
      required:
      - roleId
      additionalProperties: false
    V2PermissionsListPermissionsResponseData:
      type: array
      maxItems: 1000
      description: Array of permission objects with complete configuration details.
      items:
        $ref: '#/components/schemas/Permission'
    V2PermissionsListRolesResponseData:
      type: array
      maxItems: 1000
      description: Array of roles with their assigned permissions.
      items:
        $ref: '#/components/schemas/Role'
    V2RatelimitDeleteOverrideResponseData:
      type: object
      additionalProperties: false
      description: Empty response object. A successful response indicates the override was successfully deleted. The operation
        is immediate - as soon as this response is received, the override no longer exists and affected identifiers have reverted
        to using the default rate limit for the namespace. No other data is returned as part of the deletion operation.
    RatelimitOverride:
      type: object
      additionalProperties: false
      properties:
        overrideId:
          description: The unique identifier of this specific rate limit override. This ID is generated when the override
            is created and can be used for management operations like updating or deleting the override.
          type: string
          minLength: 1
          maxLength: 255
        duration:
          description: The duration in milliseconds for this override's rate limit window. This may differ from the default
            duration for the namespace, allowing custom time windows for specific entities. After this duration elapses, the
            rate limit counter for affected identifiers resets to zero.
          format: int64
          type: integer
          minimum: 1000
        identifier:
          description: 'The identifier pattern this override applies to. This determines which entities receive the custom
            rate limit.


            This can be:

            - An exact identifier for a specific entity

            - A pattern with wildcards for matching multiple entities


            Wildcard examples:

            - ''admin_*'' matches any identifier starting with ''admin_''

            - ''*_test'' matches any identifier ending with ''_test''

            - ''*premium*'' matches any identifier containing ''premium''


            More complex patterns can combine multiple wildcards. Detailed documentation on pattern matching rules is available
            at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules'
          type: string
          minLength: 1
          maxLength: 255
        limit:
          description: 'The maximum number of requests allowed for entities matching this override. This replaces the default
            limit for the namespace when applied.


            Common use cases:

            - Higher limits for premium customers

            - Reduced limits for abusive or suspicious entities

            - Zero limit to completely block specific patterns

            - Custom tier-based limits for different customer segments'
          format: int64
          type: integer
          minimum: 0
      required:
      - overrideId
      - duration
      - identifier
      - limit
    V2RatelimitLimitResponseData:
      type: object
      properties:
        limit:
          description: 'The maximum number of operations allowed within the time window. This reflects either the default
            limit specified in the request or an override limit if one exists for this identifier.


            This value helps clients understand their total quota for the current window.'
          format: int64
          type: integer
        remaining:
          description: 'The number of operations remaining in the current window before the rate limit is exceeded. Applications
            should use this value to:


            - Implement client-side throttling before hitting limits

            - Display usage information to end users

            - Trigger alerts when approaching limits

            - Adjust request patterns based on available capacity


            When this reaches zero, requests will be rejected until the window resets.'
          format: int64
          type: integer
        reset:
          description: 'The Unix timestamp in milliseconds when the rate limit window will reset and ''remaining'' will return
            to ''limit''.


            This timestamp enables clients to:

            - Calculate and display wait times to users

            - Implement intelligent retry mechanisms

            - Schedule requests to resume after the reset

            - Implement exponential backoff when needed


            The reset time is based on a sliding window from the first request in the current window.'
          format: int64
          type: integer
        success:
          description: 'Whether the request passed the rate limit check. If true, the request is allowed to proceed. If false,
            the request has exceeded the rate limit and should be blocked or rejected.


            You MUST check this field to determine if the request should proceed, as the endpoint always returns `HTTP 200`
            even when rate limited.'
          type: boolean
        overrideId:
          description: 'If a rate limit override was applied for this identifier, this field contains the ID of the override
            that was used. Empty when no override is in effect.


            This can be useful for:

            - Debugging which override rule was matched

            - Tracking the effects of specific overrides

            - Understanding why limits differ from default values'
          type: string
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      required:
      - limit
      - remaining
      - reset
      - success
    V2RatelimitListOverridesResponseData:
      type: array
      items:
        $ref: '#/components/schemas/RatelimitOverride'
    V2RatelimitMultiLimitResponseData:
      type: object
      description: Container for multi-limit rate limit check results
      required:
      - passed
      - limits
      properties:
        passed:
          type: boolean
          description: 'Overall success indicator for all rate limit checks. This is true if ALL individual rate limit checks
            passed (all have success: true), and false if ANY check failed.


            Use this as a quick indicator to determine if the request should proceed.'
        limits:
          type: array
          description: Array of individual rate limit check results, one for each rate limit check in the request
          items:
            $ref: '#/components/schemas/V2RatelimitMultiLimitCheck'
    V2RatelimitMultiLimitCheck:
      type: object
      properties:
        namespace:
          description: The namespace this rate limit result corresponds to. Use this field to correlate the response with
            the request when checking multiple rate limits.
          type: string
        identifier:
          description: The identifier this rate limit result corresponds to. Use this field to correlate the response with
            the request when checking multiple rate limits.
          type: string
        limit:
          description: 'The maximum number of operations allowed within the time window. This reflects either the default
            limit specified in the request or an override limit if one exists for this identifier.


            This value helps clients understand their total quota for the current window.'
          format: int64
          type: integer
        remaining:
          description: 'The number of operations remaining in the current window before the rate limit is exceeded. Applications
            should use this value to:


            - Implement client-side throttling before hitting limits

            - Display usage information to end users

            - Trigger alerts when approaching limits

            - Adjust request patterns based on available capacity


            When this reaches zero, requests will be rejected until the window resets.'
          format: int64
          type: integer
        reset:
          description: 'The Unix timestamp in milliseconds when the rate limit window will reset and ''remaining'' will return
            to ''limit''.


            This timestamp enables clients to:

            - Calculate and display wait times to users

            - Implement intelligent retry mechanisms

            - Schedule requests to resume after the reset

            - Implement exponential backoff when needed


            The reset time is based on a sliding window from the first request in the current window.'
          format: int64
          type: integer
        passed:
          description: 'Whether the request passed the rate limit check. If true, the request is allowed to proceed. If false,
            the request has exceeded the rate limit and should be blocked or rejected.


            You MUST check this field to determine if the request should proceed, as the endpoint always returns `HTTP 200`
            even when rate limited.'
          type: boolean
        overrideId:
          description: 'If a rate limit override was applied for this identifier, this field contains the ID of the override
            that was used. Empty when no override is in effect.


            This can be useful for:

            - Debugging which override rule was matched

            - Tracking the effects of specific overrides

            - Understanding why limits differ from default values'
          type: string
          x-go-type-skip-optional-pointer: true
          x-go-type-skip-optional-pointer-with-omitzero: true
      required:
      - namespace
      - identifier
      - limit
      - remaining
      - reset
      - passed
    V2RatelimitSetOverrideResponseData:
      type: object
      properties:
        overrideId:
          description: 'The unique identifier for the newly created or updated rate limit override. This ID can be used to:


            - Reference this specific override in subsequent API calls

            - Delete or modify this override later

            - Track which override is being applied in rate limit responses

            - Associate override effects with specific rules in analytics


            Store this ID if you need to manage the override in the future.'
          type: string
      required:
      - overrideId