const { result, error } = await unkey.identities.create({
  externalId: "user_123",
  ratelimits: [
    {
      name: "tokens",
      limit: 10,
      duration: 1000,
    },
  ],
});

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": {
    "identityId": "id_123"
  }
}
const { result, error } = await unkey.identities.create({
  externalId: "user_123",
  ratelimits: [
    {
      name: "tokens",
      limit: 10,
      duration: 1000,
    },
  ],
});

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": {
    "identityId": "id_123"
  }
}

​
Request

​
externalId
string
required

The id of this identity in your system.

This usually comes from your authentication provider and could be a userId, organisationId or even an email.

It does not matter what you use, as long as it uniquely identifies something in your application.

externalIds are unique across your workspace and therefore a CONFLICT error is returned when you try to create duplicates.

Minimum length: 3

Example: "user_123"

​
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"
}
​
ratelimits
object[]

Attach ratelimits to this identity.

When verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits.

​
Response

​
identityId
string
required

The id of the identity. Used internally, you do not need to store this.

Example: "id_123"