POST
/
v1
/
migrations.createKeys
curl --request POST \
  --url https://api.unkey.dev/v1/migrations.createKeys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "apiId": "api_123",
    "prefix": "<string>",
    "name": "my key",
    "plaintext": "<string>",
    "hash": {
      "value": "<string>",
      "variant": "sha256_base64"
    },
    "start": "unkey_32kq",
    "ownerId": "team_123",
    "meta": {
      "billingTier": "PRO",
      "trialEnds": "2023-06-16T17:16:37.161Z"
    },
    "roles": [
      "admin",
      "finance"
    ],
    "permissions": [
      "domains.create_record",
      "say_hello"
    ],
    "expires": 1623869797161,
    "remaining": 1000,
    "refill": {
      "interval": "daily",
      "amount": 100
    },
    "ratelimit": {
      "type": "fast",
      "limit": 10,
      "refillRate": 1,
      "refillInterval": 60
    },
    "enabled": true,
    "environment": "<string>"
  }
]'
{
  "keyIds": [
    "key_123",
    "key_456"
  ]
}

Add existing keys to unkey by specifying the key hash and other settings.

This endpoint supports bulk inserts of up to 100 keys at a time. If you have more keys, you can call this endpoint multiple times. If any operation fails (e.g., due to a duplicate key), everything will be rolled back and no keys are created.

​
Changelog

DateChanges
May 08 2024Introduced endpoint

Authorizations

Authorization
string
headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json · object[]
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 automatically added if you are defining a prefix, for example: "prefix": "abc" will result in a key like abc_xxxxxxxxx

name
string

The name for your Key. This is not customer facing.

plaintext
string

The raw key in plaintext. If provided, unkey encrypts this value and stores it securely. Provide either hash or plaintext

hash
object

Provide either hash or plaintext

start
string

The first 4 characters of the key. If a prefix is used, it should be the prefix plus 4 characters.

ownerId
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.

meta
object

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

roles
string[]

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

permissions
string[]

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

expires
integer

You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.

remaining
integer

You can limit the number of requests a key can make. Once a key reaches 0 remaining requests, it will automatically be disabled and is no longer valid unless you update it.

refill
object

Unkey enables you to refill verifications for each key at regular intervals.

ratelimit
object

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

enabled
boolean
default: true

Sets if key is enabled or disabled. Disabled keys are not valid.

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

200 - application/json
keyIds
string[]
required

The ids of the keys. This is not a secret and can be stored as a reference if you wish. You need the keyId to update or delete a key later.

Was this page helpful?

Ratelimit anything