Official Libraries
- @unkey/api
- Overview
- Keys
- APIs
- Ratelimits
- @unkey/ratelimit
- @unkey/nextjs
- @unkey/hono
- @unkey/cache
- unkey-go
- unkey.py
- Elixir
- Nuxt
- Rust
- Springboot
Verify
Verify a key
import { verifyKey } from "@unkey/api";
const { result, error } = await verifyKey({ key: "key_123", apiId: "api_123" });
if (error) {
// handle potential network or bad request error
// a link to our docs will be in the `error.docs` field
console.error(error.message);
return;
}
if (!result.valid) {
// do not grant access
return;
}
// process request
console.log(result);
{
result: {
"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",
"identity": {
"id": "<string>",
"externalId": "<string>",
"meta": {}
}
}
}
Verify a key from your users.
Request
The key you want to verify.
The api this key belongs to. This will be required soon.
Override the behavior of the ratelimit for this verification.
The cost of this verification. This will be subtracted from the ratelimit. Use this if you need to ratelimit based on what the user is trying to access. For example, you may want to ratelimit a user based on the tokens they are using in the context of LLM APIs.
Response
The id of the key you are verifying.
Whether or not this key is valid and has passed the ratelimit. If false you
should not grant access to whatever the user is requesting
The name of the key you are verifying.
If you have set an ownerId on this key it is returned here. You can use this
to clearly authenticate a user in your system.
This is the meta data you have set when creating the key.
Example:
{
"billingTier": "PRO",
"trialEnds": "2023-06-16T17:16:37.161Z"
}
The unix timestamp in milliseconds indicating when this key expires.
Shows how many more times this key may be verified before being invalidated.
Only applies to keys where you have set a remaining count.
If the key is invalid this field will be set to the reason why it is invalid.
Possible values are:
NOT_FOUND- The key does not existFORBIDDEN- You are not allowed to verify this key. For example because of additional security checks likeIP whitelistsUSAGE_EXCEEDED- The key has been used up and is no longer validRATE_LIMITED- The verification has been blocked due to ratelimitingDISABLED- the key is disabled
Shows if the key is enabled or disabled.
A list of all the permissions this key is connected to.
The environment of the key, this is what what you set when you crated the key
import { verifyKey } from "@unkey/api";
const { result, error } = await verifyKey({ key: "key_123", apiId: "api_123" });
if (error) {
// handle potential network or bad request error
// a link to our docs will be in the `error.docs` field
console.error(error.message);
return;
}
if (!result.valid) {
// do not grant access
return;
}
// process request
console.log(result);
{
result: {
"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",
"identity": {
"id": "<string>",
"externalId": "<string>",
"meta": {}
}
}
}
Was this page helpful?
import { verifyKey } from "@unkey/api";
const { result, error } = await verifyKey({ key: "key_123", apiId: "api_123" });
if (error) {
// handle potential network or bad request error
// a link to our docs will be in the `error.docs` field
console.error(error.message);
return;
}
if (!result.valid) {
// do not grant access
return;
}
// process request
console.log(result);
{
result: {
"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",
"identity": {
"id": "<string>",
"externalId": "<string>",
"meta": {}
}
}
}