UNunkeyed
identities

Update Identity

Changed on

Update an identity's metadata and rate limits. Only specified fields are modified - others remain unchanged.

Perfect for subscription changes, plan upgrades, or updating user information. Changes take effect immediately.

Important Requires identity.*.update_identity permission Rate limit changes propagate within 30 seconds

post/v2/identities.updateIdentity

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/identities.updateIdentity
  • Auth
    HTTP bearer

Request body

identitystring required

The ID of the identity to update. Accepts either the externalId (your system-generated identifier) or the identityId (internal identifier returned by the identity service).

metaobject

Replaces all existing metadata with this new metadata object. Omitting this field preserves existing metadata, while providing an empty object clears all metadata. Avoid storing sensitive data here as it's returned in verification responses. Large metadata objects increase verification latency and should stay under 10KB total size.

Example request

{
  "identity": "user_123",
  "meta": {
    "name": "Alice Smith",
    "email": "alice@example.com",
    "plan": "premium"
  },
  "ratelimits": [
    {
      "name": "requests",
      "limit": 1000,
      "duration": 3600000,
      "autoApply": true
    }
  ]
}

Response

Identity successfully updated

Example response

{
  "data": {
    "ratelimits": [
      {
        "id": "rl_1234567890abcdef",
        "name": "api_requests",
        "limit": 1000,
        "duration": 3600000,
        "autoApply": true
      }
    ]
  },
  "meta": {
    "requestId": "req_123"
  }
}

Changes