const { result, error } = await unkey.keys.create({
  apiId: "api_123",
  prefix: "xyz",
  byteLength: 16,
  externalId: "user_1234",
  meta: {
    hello: "world",
  },
  expires: 1686941966471,
  ratelimit: {
    async: true,
    duration: 1000,
    limit: 10,
  },
  remaining: 1000,
  environment: "test",
  name: "My Key",
  permissions: ["email.test"],
  roles: ["domain.manager"],
  refill: {
    interval: "monthly",
    amount: 100,
    refillDay: 15,
  },
  enabled: true,
});

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;
}

console.log(result)
{
  "result": {
    "key": "xyz_AS5HDkXXPot2MMoPHD8jnL"
    "keyId": "key_YALWkHZaA4neUa1JJoXTAw"
	}
}
const { result, error } = await unkey.keys.create({
  apiId: "api_123",
  prefix: "xyz",
  byteLength: 16,
  externalId: "user_1234",
  meta: {
    hello: "world",
  },
  expires: 1686941966471,
  ratelimit: {
    async: true,
    duration: 1000,
    limit: 10,
  },
  remaining: 1000,
  environment: "test",
  name: "My Key",
  permissions: ["email.test"],
  roles: ["domain.manager"],
  refill: {
    interval: "monthly",
    amount: 100,
    refillDay: 15,
  },
  enabled: true,
});

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;
}

console.log(result)
{
  "result": {
    "key": "xyz_AS5HDkXXPot2MMoPHD8jnL"
    "keyId": "key_YALWkHZaA4neUa1JJoXTAw"
	}
}

​
Request

​
apiId
string
required

Choose an API where this key should be created.

​
prefix
string

To make it easier for your users to understand which product an api key belongs to, you can add prefix them.

For example Stripe famously prefixes their customer ids with cus_ or their api keys with sk_live_.

The underscore is automtically added if you are defining a prefix, for example: "prefix": "abc" will result in a key like abc_xxxxxxxxx

​
byteLength
int
default:16

The bytelength used to generate your key determines its entropy as well as its length. Higher is better, but keys become longer and more annoying to handle.

The default is 16 bytes, or 2128 possible combinations

​
ownerId
string
deprecated

Deprecated, use externalId

​
externalId
string

Your user’s Id. This will provide a link between Unkey and your customer record. When validating a key, we will return this back to you, so you can clearly identify your user from their api key.

​
name
string

A way to easily identify the key by giving it a name.

​
meta
object

This is a place for dynamic meta data, anything that feels useful for you should go here

Example:

{
  "billingTier": "PRO",
  "trialEnds": "2023-06-16T17:16:37.161Z"
}
​
roles
string[]

A list of roles that this key should have. If the role does not exist, an error is thrown

Example:

["admin", "finance"]
​
permissions
string[]

A list of permissions that this key should have. If the permission does not exist, an error is thrown

Example:

["domains.create_record", "say_hello"]
​
expires
int

You can auto expire keys by providing a unix timestamp in milliseconds.

Once keys expire they will automatically be deleted and are no longer valid.

​
ratelimit
Object

Unkey comes with per-key ratelimiting out of the box.

​
remaining
number

Add how many times a key can be used, for example 100. Read more here

​
refill
Object

Unkey allows automatic refill on ‘remaining’ on a ‘daily’ or ‘monthly’ interval.

​
enabled
boolean

Sets if the key is enabled or disabled.

​
recoverable
boolean

You may want to show keys again later. While we do not recommend this, we leave this option open for you.

In addition to storing the key’s hash, recoverable keys are stored in an encrypted vault, allowing you to retrieve and display the plaintext later.

https://www.unkey.com/docs/security/recovering-keys for more information.

​
environment
string

Environments allow you to divide your keyspace.

Some applications like Stripe, Clerk, WorkOS and others have a concept of “live” and “test” keys to give the developer a way to develop their own application without the risk of modifying real world resources.

When you set an environment, we will return it back to you when validating the key, so you can handle it correctly.

​
Response

​
result