POST
/
v1
/
keys.verifyKey
curl --request POST \
  --url https://api.unkey.dev/v1/keys.verifyKey \
  --header 'Content-Type: application/json' \
  --data '{
  "apiId": "api_1234",
  "key": "sk_1234",
  "authorization": {
    "permissions": "<string>"
  },
  "ratelimit": {
    "cost": 1
  },
  "ratelimits": [
    {
      "name": "tokens",
      "cost": 1,
      "identifier": "<string>",
      "limit": 123,
      "duration": 123
    }
  ]
}'
{
  "keyId": "key_1234",
  "valid": true,
  "name": "Customer X",
  "ownerId": "user_123",
  "meta": {
    "roles": [
      "admin",
      "user"
    ],
    "stripeCustomerId": "cus_1234"
  },
  "expires": 123,
  "ratelimit": {
    "limit": 10,
    "remaining": 9,
    "reset": 3600000
  },
  "remaining": 1000,
  "code": "VALID",
  "enabled": true,
  "permissions": [
    "dns.record.update",
    "dns.record.delete"
  ],
  "environment": "test"
}

​
Changelog

DateChanges
Dec 06 2023Introduced endpoint

Body

application/json
apiId
string

The id of the api where the key belongs to. This is optional for now but will be required soon. The key will be verified against the api's configuration. If the key does not belong to the api, the verification will fail.

key
string
required

The key to verify

authorization
object

Perform RBAC checks

ratelimit
object
ratelimits
object[]

Response

200 - application/json
keyId
string

The id of the key

valid
boolean
required

Whether the key is valid or not. A key could be invalid for a number of reasons, for example if it has expired, has no more verifications left or if it has been deleted.

name
string

The name of the key, give keys a name to easily identifiy their purpose

ownerId
string

The id of the tenant associated with this key. Use whatever reference you have in your system to identify the tenant. When verifying the key, we will send this field back to you, so you know who is accessing your API.

meta
object

Any additional metadata you want to store with the key

expires
integer

The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring.

ratelimit
object

Multi ratelimits TODO:

remaining
integer

The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit.

code
enum<string>
required

A machine readable code why the key is not valid. Possible values are:

  • VALID: the key is valid and you should proceed
  • NOT_FOUND: the key does not exist or has expired
  • FORBIDDEN: the key is not allowed to access the api
  • USAGE_EXCEEDED: the key has exceeded its request limit
  • RATE_LIMITED: the key has been ratelimited
  • UNAUTHORIZED: the key is not authorized
  • DISABLED: the key is disabled
  • INSUFFICIENT_PERMISSIONS: you do not have the required permissions to perform this action
Available options:
VALID,
NOT_FOUND,
FORBIDDEN,
USAGE_EXCEEDED,
RATE_LIMITED,
UNAUTHORIZED,
DISABLED,
INSUFFICIENT_PERMISSIONS
enabled
boolean

Sets the key to be enabled or disabled. Disabled keys will not verify.

permissions
string[]

A list of all the permissions this key is connected to.

environment
string

The environment of the key, this is what what you set when you crated the key

Was this page helpful?

Create a keyRetrieve a key by ID