If you prefer a typed experience over calling http endpoints directly, you can use our sdk @unkey/api.


 npm install @unkey/api

Unkey Root Key

When creating, revoking or updating resources, you will need your root key — you can create a new one in the settings. Afterwards you need to provide it to the client:

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

const unkey = new Unkey({ rootKey: "<UNKEY_ROOT_KEY>" });

Always keep your root key safe and reset it if you suspect it has been compromised.

Response format

Because forgetting to handle thrown errors properly in javascript is often forgotten, we have decided to explicitely return errors to be handled. Fortunately typescript helps us here and everything is typesafe.

Every method returns either an error or a result field, never both and never none.

  result: T // the result depends on what method you called

Checking for errors

To check for errors you use the error property, our errors are easy to read and provide a link to our documentation for more information.

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

const { result, error } = await verifyKey("key_123");

if (error) {
  // handle potential network or bad request error
  // a link to our docs will be in the `error.docs` field

if (!result.valid) {
  // do not grant access

// process request


The constructor accepts some options to customize the behavior:

Base Url

Run all requests agaisnt your own instance of unkey hosted on your own infrastructure.

default: "https://api.unkey.dev"

The age of the user. Cannot be less than 0

const unkey = new Unkey({
  baseUrl: "https://my.domain"


By default the client will retry on network errors, you can customize this behavior:


How often to retry

(retryCount: number) => number

A function that returns how many milliseconds to wait until the next attempt is made.

const unkey = new Unkey({
  // ...
  retry: {
    attempts: 3,
    backoff: (retryCount) => retryCount * 1000


Configure the fetch cache behavior.

As of October 2023, the cache option is not yet implemented in cloudflare workers and will throw an error if used.


Available options are: default, force-cache, no-cache, no-store, only-if-cached or reload.

const unkey = new Unkey({
  // ...
  cache: "no-cache"

Disable telemetry

By default, Unkey collects anonymous telemetry data to help us understand which versions of our SDK is being used, and in which environment.

If you wish to disable this, you can do so by passing a boolean flag to the constructor:

const unkey = new Unkey({
  disableTelemetry: true

Was this page helpful?