UNunkeyed
keys

Verify API key

Changed on

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 credential needs one of:

  • api.*.verify_key (verify keys in any API)
  • api.<api_id>.verify_key (verify keys in specific API)
  • unkey:v1:<workspace_id>:keyspaces/*/keys/*#verify_key (verify keys in any keyspace)
  • unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#verify_key (verify keys in a specific keyspace)
  • unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#verify_key (verify a specific key)

Note: If your credential lacks permission to verify this key, the response is HTTP 200 with valid: false and code: NOT_FOUND. This does not distinguish a missing key from an inaccessible key.

post/v2/keys.verifyKey

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/keys.verifyKey
  • Auth
    HTTP bearer

Request body

keystring required

The API key to verify, exactly as provided by your user. Include any prefix - even small changes will cause verification to fail.

tagsstring[]

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.

permissionsstring

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.
keyspacesstring[]

Restricts verification to keys in these keyspaces, matched by exact ID. Omit this field to verify without a keyspace restriction. A failed keyspace check returns NOT_FOUND without consuming credits or rate limits.

migrationIdstring

Migrate keys on demand from your previous system. Reach out for migration support at support@unkey.dev

Example request

{
  "key": "sk_1234abcdef",
  "tags": [
    "endpoint=/users/profile",
    "method=GET",
    "region=us-east-1",
    "clientVersion=2.3.0",
    "feature=premium"
  ],
  "permissions": "documents.read AND users.view",
  "credits": {
    "cost": 5
  },
  "keyspaces": [
    "ks_1234abcd"
  ],
  "ratelimits": [
    {
      "name": "tokens",
      "cost": 2,
      "limit": 50,
      "duration": 600000
    }
  ],
  "migrationId": "m_1234abcd"
}

Response

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.

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "identity": {
      "ratelimits": [
        {
          "id": "rl_1234567890abcdef",
          "name": "api_requests",
          "limit": 1000,
          "duration": 3600000,
          "autoApply": true
        }
      ]
    },
    "ratelimits": [
      {
        "id": "rl_1234567890abcdef",
        "name": "api_requests",
        "limit": 1000,
        "duration": 3600000,
        "reset": 3600000,
        "remaining": 999,
        "autoApply": true
      }
    ]
  }
}

Changes

  • 4817d747f52fRevision changes
    • info

      removed the non-success response with the status

  • fdfccf099c7dRevision changes
    • warning

      the // request property's max was set to 9223372036854775808.00

    • warning

      the // request property's max was set to 31536000000.00

    • warning

      the // request property's max was set to 9223372036854775808.00