POST
/
v1
/
identities.createIdentity
Create identity
curl --request POST \
  --url https://api.unkey.dev/v1/identities.createIdentity \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "externalId": "user_123",
  "meta": {},
  "ratelimits": [
    {
      "name": "tokens",
      "limit": 10,
      "duration": 1000
    }
  ]
}'
{
  "identityId": "id_123"
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
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

Attach metadata to this identity that you need to have access to when verifying a key.

This will be returned as part of the verifyKey response.

​
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

The configuration for an api

​
identityId
string
required

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

Example:

"id_123"