POST
/
v1
/
keys.verifyKey

Changelog

DateChanges
Dec 06 2023Introduced endpoint
Jul 08 2024Added EXPIRED code

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
deprecated

Use 'ratelimits' with [{ name: "default", cost: 2}]

ratelimits
object[]

You can check against multiple ratelimits when verifying a key. Let's say you are building an app that uses AI under the hood and you want to limit your customers to 500 requests per hour, but also ensure they use up less than 20k tokens per day.

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

The ratelimit configuration for this key. If this field is null or undefined, the key has no ratelimit.

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
  • EXPIRED: The key was only valid for a certain time and has expired.

These are validation codes, the HTTP status will be 200.

Available options:
VALID,
NOT_FOUND,
FORBIDDEN,
USAGE_EXCEEDED,
RATE_LIMITED,
UNAUTHORIZED,
DISABLED,
INSUFFICIENT_PERMISSIONS,
EXPIRED
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

identity
object

The associated identity of this key.