@unkey/api - Unkey Docs

Use @unkey/api to call the whole Unkey API from TypeScript. The current version is . Create one Unkey client. Its properties (keys, apis, ratelimit, identities, permissions, deployments, and so on) group the methods the same way as the API reference.

You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys, and pass it as Authorization: Bearer <root key>. See Permission reference for every permission.

Install

npm add @unkey/api

pnpm add @unkey/api

bun add @unkey/api

yarn add @unkey/api

It works with CommonJS and ES modules. Supported runtimes are listed in RUNTIMES.md.

Construct the client

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

const unkey = new Unkey({
  rootKey: process.env.UNKEY_ROOT_KEY ?? "",
});

rootKey is your root key. Methods that use a different credential, such as the portal endpoints, take it as an argument on each call.

Verify a key

const result = await unkey.keys.verifyKey({
  key: "prod_abc123",
  permissions: "documents.read", // optional permission query
  tags: ["endpoint=/documents"],  // optional, for analytics filtering
});

if (result.data.valid) {
  console.log(result.data.keyId, result.data.permissions);
} else {
  console.log(result.data.code); // NOT_FOUND | FORBIDDEN | INSUFFICIENT_PERMISSIONS | USAGE_EXCEEDED | RATE_LIMITED | DISABLED | EXPIRED
}

An invalid key isn’t an error: data.valid is false and data.code says why. You can also send credits for a custom cost and ratelimits to check named limits. See Verifying keys, and the endpoint is keys.verifyKey.

Create a key

const created = await unkey.keys.createKey({
  apiId: "api_1234abcd",
  prefix: "prod",
  name: "Payment service",
  externalId: "user_42",
  permissions: ["documents.read"],
  enabled: true,
});

console.log(created.data.keyId);
console.log(created.data.key); // shown once; store or hand it to the user now

Optional fields include byteLength, meta, roles, expires (Unix milliseconds), credits, ratelimits, and recoverable. See Creating keys for what they do and keys.createKey for the full schema.

Apply a rate limit

const rl = await unkey.ratelimit.limit({
  namespace: "email.send",
  identifier: "user_42",
  limit: 10,
  duration: 60_000, // milliseconds
  cost: 1,
});

if (!rl.data.success) {
  // rl.data.remaining and rl.data.reset (Unix ms) tell the caller when to retry
}

The endpoint is ratelimit.limit. For rate limiting without a client instance and with a built-in timeout fallback, use @unkey/ratelimit, which wraps this call.

Handle errors

HTTP errors throw an UnkeyError, with message, statusCode, headers, body, and rawResponse. Each status has its own subclass with a typed data$ holding the API’s meta and error fields.

import * as errors from "@unkey/api/models/errors";

try {
  await unkey.keys.getKey({ keyId: "key_1234abcd" });
} catch (err) {
  if (err instanceof errors.NotFoundErrorResponse) {
    console.log(err.data$.meta.requestId, err.data$.error.detail);
  } else if (err instanceof errors.UnkeyError) {
    console.log(err.statusCode, err.message);
  } else {
    throw err; // ConnectionError, RequestTimeoutError, and other client-side failures
  }
}

The subclasses are BadRequestErrorResponse (400), UnauthorizedErrorResponse (401), ForbiddenErrorResponse (403), NotFoundErrorResponse (404), ConflictErrorResponse (409), GoneErrorResponse (410), PreconditionFailedErrorResponse (412), UnprocessableEntityErrorResponse (422), TooManyRequestsErrorResponse (429), InternalServerErrorResponse (500), and ServiceUnavailableErrorResponse (503). Each method’s page in the API reference, for example keys.getKey, lists which ones it can throw. See also API errors.

Retries and standalone functions

Calls retry 5xx responses and connection errors by default, waiting 50 ms at first and growing 1.5 times each retry, up to 1 s per wait and 10 s in total. To change this, pass { retries: { strategy: "backoff", ... } } as the second argument of a call, or retryConfig to the constructor. To turn it off, pass { retries: { strategy: "none" } }. To keep your bundle small, every method is also a standalone function (keysVerifyKey, keysCreateKey, ratelimitLimit, and so on) that takes the client as its first argument. See FUNCTIONS.md.

Next steps

@unkey/hono and @unkey/nextjs

Let middleware call verifyKey for you.

API reference

Every method, request field, and error per endpoint.

​Install

​Construct the client

​Verify a key

​Create a key

​Apply a rate limit

​Handle errors

​Retries and standalone functions

​Next steps

@unkey/hono and @unkey/nextjs

API reference

Install

Construct the client

Verify a key

Create a key

Apply a rate limit

Handle errors

Retries and standalone functions

Next steps