Get API Key

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

Request

string

required

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.Pattern: ^[a-zA-Z0-9_]+$Example: key_1234abcd

boolean

default:"false"

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.

Response

string

required

The unique identifier for this key in Unkey’s system.

string

The prefix of the key for visual identification.

boolean

Whether the key is currently active.

string

Human-readable name for the key.

string

The full plaintext key value (only when decrypt=true and key is recoverable).

integer

Unix timestamp in milliseconds when the key was created.

integer

Unix timestamp in milliseconds when the key expires (if set).

object

Custom metadata attached to the key.

array

Array of permission strings assigned to the key.

array

Array of role names assigned to the key.

object

Credit balance and refill configuration.

integer

Current credit balance.

object

Automatic refill settings.

array

Array of rate limit configurations attached to the key.

object

Identity information if the key is associated with an identity.

Examples

curl -X POST https://api.unkey.com/v2/keys.getKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_1234abcd"
  }'

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ token: process.env.UNKEY_ROOT_KEY });

const result = await unkey.keys.get({
  keyId: "key_1234abcd",
});

console.log(result);

With Decryption

curl -X POST https://api.unkey.com/v2/keys.getKey \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_5678efgh",
    "decrypt": true
  }'

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ token: process.env.UNKEY_ROOT_KEY });

const result = await unkey.keys.get({
  keyId: "key_5678efgh",
  decrypt: true,
});

console.log(result.result?.plaintext);

Response Example

{
  "meta": {
    "requestId": "req_1234abcd"
  },
  "data": {
    "keyId": "key_1234abcd",
    "start": "sk_prod",
    "enabled": true,
    "name": "Production API Key",
    "createdAt": 1704067200000,
    "expires": 1735689600000,
    "meta": {
      "plan": "premium",
      "userId": "user_5678",
      "environment": "production"
    },
    "permissions": [
      "documents.read",
      "documents.write"
    ],
    "roles": [
      "editor"
    ],
    "credits": {
      "remaining": 8500,
      "refill": {
        "amount": 10000,
        "interval": "monthly",
        "refillDay": 1
      }
    }
  }
}

Overview

Keys

APIs

Rate Limiting

Identities

Analytics

Permissions

Required Permissions

Request

Response

Examples

With Decryption

Response Example

​Required Permissions

​Request

​Response

​Examples

​With Decryption

​Response Example

Required Permissions

Request

Response

Examples

With Decryption

Response Example