Sign in

v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
keys

Verify API key

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 has no verify permissions at all, you will receive a 403 Forbidden error. If your credential has verify permissions for a different API or keyspace than the key you're verifying, you will receive a 200 response with code: NOT_FOUND to avoid leaking key existence.

post/v2/keys.verifyKey

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.
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
  },
  "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
      }
    ]
  }
}