---
title: "Update Identity"
method: POST
path: "/v2/identities.updateIdentity"
tags: ["identities"]
---

# Update Identity

`POST /v2/identities.updateIdentity`

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

## Request body

- V2IdentitiesUpdateIdentityRequestBody
  - `identity` string, 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).
  - `meta` object — 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.
  - `ratelimits` RatelimitRequest[] — Replaces all existing identity rate limits with this complete list of rate limits. Omitting this field preserves existing rate limits, while providing an empty array removes all rate limits. These limits are shared across all keys belonging to this identity, preventing abuse through multiple keys. Rate limit changes take effect immediately but may take up to 30 seconds to propagate across all regions.
    - `name` string, required — The name of this rate limit. This name is used to identify which limit to check during key verification. Best practices for limit names: - Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads' - Be consistent with naming conventions across your application - Create separate limits for different resource types or operation costs - Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training') You will reference this exact name when verifying keys to check against this specific limit.
    - `limit` integer, required — The maximum number of operations allowed within the specified time window. When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect: - Your infrastructure capacity and scaling limitations - Fair usage expectations for your service - Different tier levels for various user types - The relative cost of the operations being limited Higher values allow more frequent access but may impact service performance.
    - `duration` integer, required — The duration for each ratelimit window in milliseconds. This controls how long the rate limit counter accumulates before resetting. Common values include: - 1000 (1 second): For strict per-second limits on high-frequency operations - 60000 (1 minute): For moderate API usage control - 3600000 (1 hour): For less frequent but costly operations - 86400000 (24 hours): For daily quotas Shorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion.
    - `autoApply` boolean, required — Whether this ratelimit should be automatically applied when verifying a key.

## Response `200`

Identity successfully updated

- V2IdentitiesUpdateIdentityResponseBody
  - `data` Identity, required
    - `id` string, required — Identity ID
    - `externalId` string, required — External identity ID
    - `meta` object — Identity metadata
    - `ratelimits` RatelimitResponse[] — Identity ratelimits
      - `id` string, required — Unique identifier for this rate limit configuration.
      - `name` string, required — Human-readable name for this rate limit.
      - `limit` integer, required — Maximum requests allowed within the time window.
      - `duration` integer, required — Rate limit window duration in milliseconds.
      - `autoApply` boolean, required — Whether this rate limit was automatically applied when verifying the key.
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `identity.*.update_identity`)
- `404` — Not Found - Identity with the specified ID or externalId doesn't exist
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/4bd11a7252bc/schema)