POST
/
v1
/
identities.createIdentity

Identities are in public beta. Please report any issues to support@unkey.dev

Create a new identity in the system. This might not be necessary as newly created keys automatically create an identity if required.

Identities map your users, organisations or other entities to keys. They can be used to share metadata and limits.

Changelog

DateChanges
Jul 17 2024Introduced endpoint

Authorizations

Authorization
string
headerrequired

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 PRECONDITION_FAILED error is returned when you try to create duplicates.

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

200 - application/json
identityId
string
required

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