Unkey v2
MCP for all of Unkey V2
Install
Select a method below to install the server.
Cursor
unkey_v2_gateway_update_policy
Update a single policy in place without resending the environment's full
policy list. The policy keeps its id and its position in the evaluation
order, and all other policies are untouched.
Omitted fields keep their stored values; at least one updatable field
must be provided. Setting `match` to null removes all match expressions
so the policy applies to every request. Providing one of `keyauth`,
`ratelimit`, `firewall` or `openapi` replaces the policy's rule
entirely, including switching its type; at most one may be set.
Policy ids are regenerated whenever `gateway.setPolicies` replaces the
list, so fetch current ids via `gateway.listPolicies` first.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.update_policy` (for any environment)
- `environment.<environment_id>.update_policy` (for a specific environment)
▾
Update a single policy in place without resending the environment's full
policy list. The policy keeps its id and its position in the evaluation
order, and all other policies are untouched.
Omitted fields keep their stored values; at least one updatable field
must be provided. Setting `match` to null removes all match expressions
so the policy applies to every request. Providing one of `keyauth`,
`ratelimit`, `firewall` or `openapi` replaces the policy's rule
entirely, including switching its type; at most one may be set.
Policy ids are regenerated whenever `gateway.setPolicies` replaces the
list, so fetch current ids via `gateway.listPolicies` first.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.update_policy` (for any environment)
- `environment.<environment_id>.update_policy` (for a specific environment)
Open-world
unkey_v2_gateway_set_policies
Replace an environment's gateway policies in a single atomic request.
Policies run at the edge before requests reach your app: verify API keys,
rate limit, block requests outright, or validate them against your
OpenAPI spec.
Policies are an ordered list: the gateway evaluates them top to bottom
and the first rejection short-circuits the request.
Each policy sets exactly one of `keyauth`, `ratelimit`, `firewall` or
`openapi`, plus optional `match` expressions restricting which requests
it applies to.
Every call is a full replace: the environment's policies become exactly
the request list in the given order, and the server generates a fresh id
for each one. An empty list removes all policies. The operation is
atomic: if any policy is invalid, nothing is written.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.set_policies` (for any environment)
- `environment.<environment_id>.set_policies` (for a specific environment)
▾
Replace an environment's gateway policies in a single atomic request.
Policies run at the edge before requests reach your app: verify API keys,
rate limit, block requests outright, or validate them against your
OpenAPI spec.
Policies are an ordered list: the gateway evaluates them top to bottom
and the first rejection short-circuits the request.
Each policy sets exactly one of `keyauth`, `ratelimit`, `firewall` or
`openapi`, plus optional `match` expressions restricting which requests
it applies to.
Every call is a full replace: the environment's policies become exactly
the request list in the given order, and the server generates a fresh id
for each one. An empty list removes all policies. The operation is
atomic: if any policy is invalid, nothing is written.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.set_policies` (for any environment)
- `environment.<environment_id>.set_policies` (for a specific environment)
Open-world
unkey_v2_keys_update_key
Update key properties in response to plan changes, subscription updates, or account status changes.
Use this for user upgrades/downgrades, role modifications, or administrative changes. Supports partial updates - only specify fields you want to change. Set fields to null to clear them.
**Important**: Permissions and roles are replaced entirely. Use dedicated add/remove endpoints for incremental changes.
**Required Permissions**
Your credential must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#update_key` (to update keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#update_key` (to update keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#update_key` (to update a specific key)
**Side Effects**
If you specify an `externalId` that doesn't exist, a new identity will be automatically created and linked to the key. Permission updates will auto-create any permissions that don't exist in your workspace. Changes take effect immediately but may take up to 30 seconds to propagate to all edge regions due to cache invalidation.
▾
Update key properties in response to plan changes, subscription updates, or account status changes.
Use this for user upgrades/downgrades, role modifications, or administrative changes. Supports partial updates - only specify fields you want to change. Set fields to null to clear them.
**Important**: Permissions and roles are replaced entirely. Use dedicated add/remove endpoints for incremental changes.
**Required Permissions**
Your credential must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#update_key` (to update keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#update_key` (to update keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#update_key` (to update a specific key)
**Side Effects**
If you specify an `externalId` that doesn't exist, a new identity will be automatically created and linked to the key. Permission updates will auto-create any permissions that don't exist in your workspace. Changes take effect immediately but may take up to 30 seconds to propagate to all edge regions due to cache invalidation.
Open-world
unkey_v2_keys_migrate_keys
Returns HTTP 200 even on partial success; hashes that could not be migrated are listed under `data.failed`.
**Required Permissions**
Your root key must have one of the following permissions for basic key information:
- `api.*.create_key` (to migrate keys to any API)
- `api.<api_id>.create_key` (to migrate keys to a specific API)
▾
Returns HTTP 200 even on partial success; hashes that could not be migrated are listed under `data.failed`.
**Required Permissions**
Your root key must have one of the following permissions for basic key information:
- `api.*.create_key` (to migrate keys to any API)
- `api.<api_id>.create_key` (to migrate keys to a specific API)
Open-world
unkey_v2_environments_update_settings
Update the build, runtime, and regional settings for an environment.
All settings fields are optional. Omit a field to leave it unchanged. For
nullable fields (`dockerfile`, `healthcheck`, `openapiSpecPath`), send null
to clear the value. When `regions` is present it replaces the full set of
regions for the environment.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.update_environment` (to update any environment)
- `environment.<environment_id>.update_environment` (to update a specific environment)
▾
Update the build, runtime, and regional settings for an environment.
All settings fields are optional. Omit a field to leave it unchanged. For
nullable fields (`dockerfile`, `healthcheck`, `openapiSpecPath`), send null
to clear the value. When `regions` is present it replaces the full set of
regions for the environment.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.update_environment` (to update any environment)
- `environment.<environment_id>.update_environment` (to update a specific environment)
Open-world
unkey_v2_keys_create_key
Create a new API key for user authentication and authorization.
Use this endpoint when users sign up, upgrade subscription tiers, or need additional keys. Keys are cryptographically secure and unique to the specified API namespace.
**Important**: The key is returned only once. Store it immediately and provide it to your user, as it cannot be retrieved later.
**Common use cases:**
- Generate keys for new user registrations
- Create additional keys for different applications
- Issue keys with specific permissions or limits
**Required Permissions**
Your credential needs one of:
- `api.*.create_key` (create keys in any API)
- `api.<api_id>.create_key` (create keys in specific API)
- `unkey:v1:<workspace_id>:keyspaces/*#create_key` (create keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>#create_key` (create keys in a specific keyspace)
▾
Create Key
Create a new API key for user authentication and authorization.
Use this endpoint when users sign up, upgrade subscription tiers, or need additional keys. Keys are cryptographically secure and unique to the specified API namespace.
**Important**: The key is returned only once. Store it immediately and provide it to your user, as it cannot be retrieved later.
**Common use cases:**
- Generate keys for new user registrations
- Create additional keys for different applications
- Issue keys with specific permissions or limits
**Required Permissions**
Your credential needs one of:
- `api.*.create_key` (create keys in any API)
- `api.<api_id>.create_key` (create keys in specific API)
- `unkey:v1:<workspace_id>:keyspaces/*#create_key` (create keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>#create_key` (create keys in a specific keyspace)
Open-world
unkey_v2_ratelimit_multi_limit
Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses, API clients, etc.).
Use this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own result with a top-level `passed` indicator showing if all checks succeeded.
**Response Codes**: Rate limit checks return HTTP 200 regardless of whether limits are exceeded — check the `passed` field to see if all limits passed, or the `success` field in each individual result. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
**Required Permissions**
Your root key must have one of the following permissions:
- `ratelimit.*.limit` (to check limits in any namespace)
- `ratelimit.<namespace_id>.limit` (to check limits in all specific namespaces being checked)
▾
Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses, API clients, etc.).
Use this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own result with a top-level `passed` indicator showing if all checks succeeded.
**Response Codes**: Rate limit checks return HTTP 200 regardless of whether limits are exceeded — check the `passed` field to see if all limits passed, or the `success` field in each individual result. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
**Required Permissions**
Your root key must have one of the following permissions:
- `ratelimit.*.limit` (to check limits in any namespace)
- `ratelimit.<namespace_id>.limit` (to check limits in all specific namespaces being checked)
Open-world
unkey_v2_ratelimit_limit
Check and enforce rate limits for any identifier (user ID, IP address, API client, etc.).
Use this for rate limiting beyond API keys - limit users by ID, IPs by address, or any custom identifier. Supports namespace organization, variable costs, and custom overrides.
**Response Codes**: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded — check the `success` field in the response to determine if the request should be allowed. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
**Required Permissions**
Your root key must have one of the following permissions:
- `ratelimit.*.limit` (to check limits in any namespace)
- `ratelimit.<namespace_id>.limit` (to check limits in a specific namespace)
▾
Check and enforce rate limits for any identifier (user ID, IP address, API client, etc.).
Use this for rate limiting beyond API keys - limit users by ID, IPs by address, or any custom identifier. Supports namespace organization, variable costs, and custom overrides.
**Response Codes**: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded — check the `success` field in the response to determine if the request should be allowed. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
**Required Permissions**
Your root key must have one of the following permissions:
- `ratelimit.*.limit` (to check limits in any namespace)
- `ratelimit.<namespace_id>.limit` (to check limits in a specific namespace)
Open-world
unkey_v2_ratelimit_set_override
Create or update a custom rate limit for specific identifiers, bypassing the namespace default.
Use this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency throttling.
**Important:** Overrides take effect immediately and completely replace the default limit for matching identifiers. Use wildcard patterns (e.g., `premium_*`) to match multiple identifiers.
**Permissions:** Requires `ratelimit.*.set_override` or `ratelimit.<namespace_id>.set_override`
▾
Create or update a custom rate limit for specific identifiers, bypassing the namespace default.
Use this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency throttling.
**Important:** Overrides take effect immediately and completely replace the default limit for matching identifiers. Use wildcard patterns (e.g., `premium_*`) to match multiple identifiers.
**Permissions:** Requires `ratelimit.*.set_override` or `ratelimit.<namespace_id>.set_override`
Open-world
unkey_v2_ratelimit_list_overrides
Retrieve a paginated list of all rate limit overrides in a namespace.
Use this to audit rate limiting policies, build admin dashboards, or manage override configurations.
**Important:** Results are paginated. Use the cursor parameter to retrieve additional pages when more results are available.
**Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`
▾
Retrieve a paginated list of all rate limit overrides in a namespace.
Use this to audit rate limiting policies, build admin dashboards, or manage override configurations.
**Important:** Results are paginated. Use the cursor parameter to retrieve additional pages when more results are available.
**Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`
Open-world
unkey_v2_projects_update_project
Update an existing project in your workspace, identified by its id.
The project name, slug, and delete protection setting can be changed. Omitted fields are left unchanged. Changing the slug affects the deployment domains generated for this project.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.update_project` (to update any project)
- `project.<project_id>.update_project` (to update a specific project)
▾
Update an existing project in your workspace, identified by its id.
The project name, slug, and delete protection setting can be changed. Omitted fields are left unchanged. Changing the slug affects the deployment domains generated for this project.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.update_project` (to update any project)
- `project.<project_id>.update_project` (to update a specific project)
Open-world
unkey_v2_ratelimit_get_override
Retrieve the configuration of a specific rate limit override by its identifier.
Use this to inspect override configurations, audit rate limiting policies, or debug rate limiting behavior.
**Important:** The identifier must match exactly as specified when creating the override, including wildcard patterns.
**Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`
▾
Retrieve the configuration of a specific rate limit override by its identifier.
Use this to inspect override configurations, audit rate limiting policies, or debug rate limiting behavior.
**Important:** The identifier must match exactly as specified when creating the override, including wildcard patterns.
**Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`
Open-world
unkey_v2_ratelimit_delete_override
Permanently remove a rate limit override. Affected identifiers immediately revert to the namespace default.
Use this to remove temporary overrides, reset identifiers to standard limits, or clean up outdated rules.
**Important:** Deletion is immediate and permanent. The override cannot be recovered and must be recreated if needed again.
**Permissions:** Requires `ratelimit.*.delete_override` or `ratelimit.<namespace_id>.delete_override`
▾
Permanently remove a rate limit override. Affected identifiers immediately revert to the namespace default.
Use this to remove temporary overrides, reset identifiers to standard limits, or clean up outdated rules.
**Important:** Deletion is immediate and permanent. The override cannot be recovered and must be recreated if needed again.
**Permissions:** Requires `ratelimit.*.delete_override` or `ratelimit.<namespace_id>.delete_override`
Open-world
unkey_v2_keys_verify_key
Verify an API key's validity and permissions for request authentication.
Use this endpoint on every incoming request to your protected resources. It checks key validity, permissions, rate limits, and usage quotas in a single call.
**Important**: Returns HTTP 200 for all verification outcomes — check the `valid` field in response data to determine if the key is authorized. A 429 may be returned if the workspace exceeds its API rate limit.
**Common use cases:**
- Authenticate API requests before processing
- Enforce permission-based access control
- Track usage and apply rate limits
**Required Permissions**
Your credential needs one of:
- `api.*.verify_key` (verify keys in any API)
- `api.<api_id>.verify_key` (verify keys in specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#verify_key` (verify keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#verify_key` (verify keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#verify_key` (verify a specific key)
**Note**: If your credential has no verify permissions at all, you will receive a `403 Forbidden` error. If your credential has verify permissions for a different API or keyspace than the key you're verifying, you will receive a `200` response with `code: NOT_FOUND` to avoid leaking key existence.
▾
Verify an API key's validity and permissions for request authentication.
Use this endpoint on every incoming request to your protected resources. It checks key validity, permissions, rate limits, and usage quotas in a single call.
**Important**: Returns HTTP 200 for all verification outcomes — check the `valid` field in response data to determine if the key is authorized. A 429 may be returned if the workspace exceeds its API rate limit.
**Common use cases:**
- Authenticate API requests before processing
- Enforce permission-based access control
- Track usage and apply rate limits
**Required Permissions**
Your credential needs one of:
- `api.*.verify_key` (verify keys in any API)
- `api.<api_id>.verify_key` (verify keys in specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#verify_key` (verify keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#verify_key` (verify keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#verify_key` (verify a specific key)
**Note**: If your credential has no verify permissions at all, you will receive a `403 Forbidden` error. If your credential has verify permissions for a different API or keyspace than the key you're verifying, you will receive a `200` response with `code: NOT_FOUND` to avoid leaking key existence.
Open-world
unkey_v2_projects_list_projects
Retrieve a paginated list of projects in your workspace.
Use this to build project management dashboards or to enumerate projects for administrative purposes. Results are ordered by project id and returned in pages. When `hasMore` is true, pass the returned `cursor` to fetch the next page.
**Required Permissions**
Your root key must have the following permission:
- `project.*.read_project` (to read projects in your workspace)
▾
Retrieve a paginated list of projects in your workspace.
Use this to build project management dashboards or to enumerate projects for administrative purposes. Results are ordered by project id and returned in pages. When `hasMore` is true, pass the returned `cursor` to fetch the next page.
**Required Permissions**
Your root key must have the following permission:
- `project.*.read_project` (to read projects in your workspace)
Open-world
unkey_v2_portal_create_session
Create a portal session for an end user and get the URL to redirect them to.
The URL carries a single-use exchange code valid for 15 minutes, which the portal
redeems exactly once for a 24-hour access token via `portal.exchangeCode`.
**Required Permissions**
Authorization runs in two stages, and both must pass.
First, your root key must have one of the following permissions:
- `portal.*.create_portal_session` (to mint sessions for any portal in the workspace)
- `portal.<portal_id>.create_portal_session` (to mint sessions for a specific portal)
Second, a session can never carry a capability your root key does not itself
hold. Each requested scope additionally requires the equivalent permission on
every keyspace the portal resolves to:
- `keys:read` requires `api.<api_id>.read_key` **and** `api.<api_id>.read_api`
- `keys:reroll` and `keys:create` require `api.<api_id>.create_key`, plus
`api.<api_id>.encrypt_key` when the keyspace stores encrypted keys
- `analytics:read` requires `api.<api_id>.read_analytics`
The `*` form of each is also accepted. Requesting a scope you do not hold
returns 403 for the whole request rather than minting a reduced session, so a
missing grant is visible instead of surfacing later as a broken portal.
Missing the portal permission itself returns **404**, not 403: a caller who
cannot mint for a portal is not told whether it exists.
Your root key must also be associated with a workspace that has an enabled portal.
▾
Create a portal session for an end user and get the URL to redirect them to.
The URL carries a single-use exchange code valid for 15 minutes, which the portal
redeems exactly once for a 24-hour access token via `portal.exchangeCode`.
**Required Permissions**
Authorization runs in two stages, and both must pass.
First, your root key must have one of the following permissions:
- `portal.*.create_portal_session` (to mint sessions for any portal in the workspace)
- `portal.<portal_id>.create_portal_session` (to mint sessions for a specific portal)
Second, a session can never carry a capability your root key does not itself
hold. Each requested scope additionally requires the equivalent permission on
every keyspace the portal resolves to:
- `keys:read` requires `api.<api_id>.read_key` **and** `api.<api_id>.read_api`
- `keys:reroll` and `keys:create` require `api.<api_id>.create_key`, plus
`api.<api_id>.encrypt_key` when the keyspace stores encrypted keys
- `analytics:read` requires `api.<api_id>.read_analytics`
The `*` form of each is also accepted. Requesting a scope you do not hold
returns 403 for the whole request rather than minting a reduced session, so a
missing grant is visible instead of surfacing later as a broken portal.
Missing the portal permission itself returns **404**, not 403: a caller who
cannot mint for a portal is not told whether it exists.
Your root key must also be associated with a workspace that has an enabled portal.
Open-world
unkey_v2_projects_get_project
Retrieve a single project in your workspace by its id.
Use this to fetch project details after creation, verify a project exists before performing operations, or resolve a project's metadata from its id.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.read_project` (to read any project)
- `project.<project_id>.read_project` (to read a specific project)
▾
Retrieve a single project in your workspace by its id.
Use this to fetch project details after creation, verify a project exists before performing operations, or resolve a project's metadata from its id.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.read_project` (to read any project)
- `project.<project_id>.read_project` (to read a specific project)
Open-world
unkey_v2_portal_reroll_key
Reroll an API key owned by the authenticated portal session's end user,
issuing a new key while preserving its configuration.
This is the portal-scoped variant of `keys.rerollKey`. It authenticates only
with a portal session cookie and may only reroll keys owned by the session's
external identity; any other key returns 404.
▾
Reroll an API key owned by the authenticated portal session's end user,
issuing a new key while preserving its configuration.
This is the portal-scoped variant of `keys.rerollKey`. It authenticates only
with a portal session cookie and may only reroll keys owned by the session's
external identity; any other key returns 404.
Open-world
unkey_v2_projects_create_project
Create a project to group deployments and applications under a workspace-scoped slug.
The slug you provide is the stable, caller-defined handle used to reference this project in subsequent operations (get, update, delete). It must be unique within your workspace.
**Important**: The slug cannot collide with an existing project in your workspace. A duplicate slug returns a 409 conflict.
**Required Permissions**
Your root key must have the following permission:
- `project.*.create_project` (to create projects in your workspace)
▾
Create a project to group deployments and applications under a workspace-scoped slug.
The slug you provide is the stable, caller-defined handle used to reference this project in subsequent operations (get, update, delete). It must be unique within your workspace.
**Important**: The slug cannot collide with an existing project in your workspace. A duplicate slug returns a 409 conflict.
**Required Permissions**
Your root key must have the following permission:
- `project.*.create_project` (to create projects in your workspace)
Open-world
unkey_v2_projects_delete_project
Delete an existing project in your workspace, identified by its id.
Deletion is asynchronous and eventually consistent. The project and all of its associated resources (apps, environments, deployments, custom domains) are torn down by a background workflow. A successful response indicates the deletion was enqueued, not that every resource has already been removed.
Projects with delete protection enabled cannot be deleted until protection is disabled.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.delete_project` (to delete any project)
- `project.<project_id>.delete_project` (to delete a specific project)
▾
Delete an existing project in your workspace, identified by its id.
Deletion is asynchronous and eventually consistent. The project and all of its associated resources (apps, environments, deployments, custom domains) are torn down by a background workflow. A successful response indicates the deletion was enqueued, not that every resource has already been removed.
Projects with delete protection enabled cannot be deleted until protection is disabled.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.delete_project` (to delete any project)
- `project.<project_id>.delete_project` (to delete a specific project)
Open-world
unkey_v2_portal_get_verifications
Return a verification analytics timeseries for the authenticated portal
session's end user.
Authenticates only with a portal session cookie and always restricts results
to verification events attributed to the session's external identity. Unlike
`analytics.getVerifications`, this endpoint takes a fixed time window (no
query language) and returns a zero-filled, outcome-broken-out timeseries.
Bucket granularity is chosen automatically from the window size.
▾
Return a verification analytics timeseries for the authenticated portal
session's end user.
Authenticates only with a portal session cookie and always restricts results
to verification events attributed to the session's external identity. Unlike
`analytics.getVerifications`, this endpoint takes a fixed time window (no
query language) and returns a zero-filled, outcome-broken-out timeseries.
Bucket granularity is chosen automatically from the window size.
Open-world
unkey_v2_portal_list_keys
Retrieve a paginated list of API keys owned by the authenticated portal
session's end user.
This is the portal-scoped variant of `apis.listKeys`. It authenticates only
with a portal session cookie and always restricts results to the keys owned
by the session's external identity, within the keyspaces configured on the
portal configuration. Both the identity and the keyspaces come from the
session, so the request body has no `externalId` or `apiId` field.
▾
Retrieve a paginated list of API keys owned by the authenticated portal
session's end user.
This is the portal-scoped variant of `apis.listKeys`. It authenticates only
with a portal session cookie and always restricts results to the keys owned
by the session's external identity, within the keyspaces configured on the
portal configuration. Both the identity and the keyspaces come from the
session, so the request body has no `externalId` or `apiId` field.
Open-world
unkey_v2_portal_exchange_code
Exchange a short-lived code for a long-lived portal access token.
This endpoint is unauthenticated. The code itself serves as proof of authorization.
Each code can only be redeemed once; subsequent attempts return 401.
The returned access token is valid for 24 hours and should be stored as an
httpOnly cookie or used in the Authorization header for subsequent API calls.
▾
Exchange a short-lived code for a long-lived portal access token.
This endpoint is unauthenticated. The code itself serves as proof of authorization.
Each code can only be redeemed once; subsequent attempts return 401.
The returned access token is valid for 24 hours and should be stored as an
httpOnly cookie or used in the Authorization header for subsequent API calls.
Open-world
unkey_v2_permissions_set_role_permissions
Atomically replaces all permissions directly assigned to a role. An empty `permissions` array removes every permission from the role. Permissions that do not exist are created when the caller has permission to create them.
**Required Permissions**
Your root key must have:
- `rbac.*.add_permission_to_role`
- `rbac.*.remove_permission_from_role`
When any requested permission slug does not exist, it must also have:
- `rbac.*.create_permission`
▾
Atomically replaces all permissions directly assigned to a role. An empty `permissions` array removes every permission from the role. Permissions that do not exist are created when the caller has permission to create them.
**Required Permissions**
Your root key must have:
- `rbac.*.add_permission_to_role`
- `rbac.*.remove_permission_from_role`
When any requested permission slug does not exist, it must also have:
- `rbac.*.create_permission`
Open-world
unkey_v2_permissions_list_roles
Retrieve all roles in your workspace including their assigned permissions.
Results are paginated and sorted by their id.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_role`
▾
Retrieve all roles in your workspace including their assigned permissions.
Results are paginated and sorted by their id.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_role`
Open-world
unkey_v2_permissions_list_permissions
Retrieve all permissions in your workspace.
Results are paginated and sorted by their id.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_permission`
▾
Retrieve all permissions in your workspace.
Results are paginated and sorted by their id.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_permission`
Open-world
unkey_v2_permissions_create_role
Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys. Permission slugs supplied in `permissions` are attached during creation. Missing permissions are created automatically.
**Important:** Role names must be unique within the workspace. Once created, roles are immediately available for assignment.
**Required Permissions**
Your root key must always have:
- `rbac.*.create_role`
When `permissions` is not empty, it must also have:
- `rbac.*.add_permission_to_role`
When any requested permission slug does not exist, it must also have:
- `rbac.*.create_permission`
▾
Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys. Permission slugs supplied in `permissions` are attached during creation. Missing permissions are created automatically.
**Important:** Role names must be unique within the workspace. Once created, roles are immediately available for assignment.
**Required Permissions**
Your root key must always have:
- `rbac.*.create_role`
When `permissions` is not empty, it must also have:
- `rbac.*.add_permission_to_role`
When any requested permission slug does not exist, it must also have:
- `rbac.*.create_permission`
Open-world
unkey_v2_permissions_get_role
Retrieve details about a specific role including its assigned permissions.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_role`
▾
Retrieve details about a specific role including its assigned permissions.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_role`
Open-world
unkey_v2_permissions_create_permission
Create a new permission to define specific actions or capabilities in your RBAC system. Permissions can be assigned directly to API keys or included in roles.
Use hierarchical naming patterns like `documents.read`, `admin.users.delete`, or `billing.invoices.create` for clear organization.
**Important:** Permission names must be unique within the workspace. Once created, permissions are immediately available for assignment.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.create_permission`
▾
Create a new permission to define specific actions or capabilities in your RBAC system. Permissions can be assigned directly to API keys or included in roles.
Use hierarchical naming patterns like `documents.read`, `admin.users.delete`, or `billing.invoices.create` for clear organization.
**Important:** Permission names must be unique within the workspace. Once created, permissions are immediately available for assignment.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.create_permission`
Open-world
unkey_v2_permissions_get_permission
Retrieve details about a specific permission including its name, description, and metadata.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_permission`
▾
Retrieve details about a specific permission including its name, description, and metadata.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.read_permission`
Open-world
unkey_v2_permissions_delete_role
Remove a role from your workspace. This also removes the role from all assigned API keys.
**Important:** This operation cannot be undone and immediately affects all API keys that had this role assigned.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.delete_role`
▾
Remove a role from your workspace. This also removes the role from all assigned API keys.
**Important:** This operation cannot be undone and immediately affects all API keys that had this role assigned.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.delete_role`
Open-world
unkey_v2_permissions_delete_permission
Remove a permission from your workspace. This also removes the permission from all API keys and roles.
**Important:** This operation cannot be undone and immediately affects all API keys and roles that had this permission assigned.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.delete_permission`
▾
Remove a permission from your workspace. This also removes the permission from all API keys and roles.
**Important:** This operation cannot be undone and immediately affects all API keys and roles that had this permission assigned.
**Required Permissions**
Your root key must have the following permission:
- `rbac.*.delete_permission`
Open-world
unkey_v2_keys_update_credits
Update credit quotas in response to plan changes, billing cycles, or usage purchases.
Use this for user upgrades/downgrades, monthly quota resets, credit purchases, or promotional bonuses. Supports three operations: set, increment, or decrement credits. Set to null for unlimited usage.
**Important**: Setting unlimited credits automatically clears existing refill configurations.
**Required Permissions**
Your credential must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#update_key` (to update keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#update_key` (to update keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#update_key` (to update a specific key)
**Side Effects**
Credit updates remove the key from cache immediately. Setting credits to unlimited automatically clears any existing refill settings. Changes take effect instantly but may take up to 30 seconds to propagate to all edge regions.
▾
Update credit quotas in response to plan changes, billing cycles, or usage purchases.
Use this for user upgrades/downgrades, monthly quota resets, credit purchases, or promotional bonuses. Supports three operations: set, increment, or decrement credits. Set to null for unlimited usage.
**Important**: Setting unlimited credits automatically clears existing refill configurations.
**Required Permissions**
Your credential must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#update_key` (to update keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#update_key` (to update keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#update_key` (to update a specific key)
**Side Effects**
Credit updates remove the key from cache immediately. Setting credits to unlimited automatically clears any existing refill settings. Changes take effect instantly but may take up to 30 seconds to propagate to all edge regions.
Open-world
unkey_v2_keys_whoami
Find out what key this is.
**Required Permissions**
Your credential must have one of the following permissions for basic key information:
- `api.*.read_key` (to read keys from any API)
- `api.<api_id>.read_key` (to read keys from a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#read_key` (to read keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#read_key` (to read keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#read_key` (to read a specific key)
If your credential lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existence of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your credential has the correct permissions.
▾
Find out what key this is.
**Required Permissions**
Your credential must have one of the following permissions for basic key information:
- `api.*.read_key` (to read keys from any API)
- `api.<api_id>.read_key` (to read keys from a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#read_key` (to read keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#read_key` (to read keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#read_key` (to read a specific key)
If your credential lacks permissions but the key exists, we may return a 404 status here to prevent leaking the existence of a key to unauthorized clients. If you believe that a key should exist, but receive a 404, please double check your credential has the correct permissions.
Open-world
unkey_v2_keys_set_roles
Replace all roles on a key with the specified set in a single atomic operation.
Use this to synchronize with external systems, reset roles to a known state, or apply standardized role templates. Direct permissions are never affected.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.
▾
Replace all roles on a key with the specified set in a single atomic operation.
Use this to synchronize with external systems, reset roles to a known state, or apply standardized role templates. Direct permissions are never affected.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.
Open-world
unkey_v2_keys_set_permissions
Replace all permissions on a key with the specified set in a single atomic operation.
Use this to synchronize with external systems, reset permissions to a known state, or apply standardized permission templates. Permissions granted through roles remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.
▾
Replace all permissions on a key with the specified set in a single atomic operation.
Use this to synchronize with external systems, reset permissions to a known state, or apply standardized permission templates. Permissions granted through roles remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.
Open-world
unkey_v2_identities_update_identity
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
▾
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
Open-world
unkey_v2_environments_set_environment_variables
Create or update environment variables for an environment in a single atomic
request.
By default this is an upsert: each variable in the payload is created if new
or fully overwritten if the key already exists, and any variable not in the
payload is left untouched. This lets you change one variable without
re-sending the others, which matters for write-only secrets you can no longer
read back.
Set `prune: true` to make it a full replace instead: after upserting, every
variable not in the payload is deleted. Sending `prune: true` with an empty
`variables` list resets the environment by deleting every variable.
Each variable is written exactly as sent, never merged, so omitted optional
fields fall back to their defaults rather than the previous value. Values are
always encrypted at rest. Set `kind: recoverable` to allow a value to be read
back; it defaults to `writeonly`, which can never be read back through the API.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.set_environment_variables` (for any environment)
- `environment.<environment_id>.set_environment_variables` (for a specific environment)
▾
Create or update environment variables for an environment in a single atomic
request.
By default this is an upsert: each variable in the payload is created if new
or fully overwritten if the key already exists, and any variable not in the
payload is left untouched. This lets you change one variable without
re-sending the others, which matters for write-only secrets you can no longer
read back.
Set `prune: true` to make it a full replace instead: after upserting, every
variable not in the payload is deleted. Sending `prune: true` with an empty
`variables` list resets the environment by deleting every variable.
Each variable is written exactly as sent, never merged, so omitted optional
fields fall back to their defaults rather than the previous value. Values are
always encrypted at rest. Set `kind: recoverable` to allow a value to be read
back; it defaults to `writeonly`, which can never be read back through the API.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.set_environment_variables` (for any environment)
- `environment.<environment_id>.set_environment_variables` (for a specific environment)
Open-world
unkey_v2_identities_create_identity
Create an identity to group multiple API keys under a single entity. Identities enable shared rate limits and metadata across all associated keys.
Perfect for users with multiple devices, organizations with multiple API keys, or when you need unified rate limiting across different services.
**Important**
Requires `identity.*.create_identity` permission
▾
Create an identity to group multiple API keys under a single entity. Identities enable shared rate limits and metadata across all associated keys.
Perfect for users with multiple devices, organizations with multiple API keys, or when you need unified rate limiting across different services.
**Important**
Requires `identity.*.create_identity` permission
Open-world
unkey_v2_keys_reroll_key
Generate a new API key while preserving the configuration from an existing key.
This operation creates a fresh key with a new token while maintaining all settings from the original key:
- Permissions and roles
- Custom metadata
- Rate limit configurations
- Identity associations
- Remaining credits
- Recovery settings
**Key Generation:**
- The system attempts to extract the prefix from the original key
- If prefix extraction fails, the default API prefix is used
- Key length follows the API's default byte configuration (or 16 bytes if not specified)
**Original Key Handling:**
- The original key will be revoked after the duration specified in `expiration`
- Set `expiration` to 0 to revoke immediately
- This allows for graceful key rotation with an overlap period
Common use cases include:
- Rotating keys for security compliance
- Issuing replacement keys for compromised credentials
- Creating backup keys with identical permissions
**Important:** Analytics and usage metrics are tracked at both the key level AND identity level. If the original key has an identity, the new key will inherit it, allowing you to track usage across both individual keys and the overall identity.
**Required Permissions**
Your credential must have:
- `api.*.create_key` or `api.<api_id>.create_key`
- `unkey:v1:<workspace_id>:keyspaces/*#create_key` or `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>#create_key`
- `api.*.encrypt_key` or `api.<api_id>.encrypt_key` (only when the original key is recoverable)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#encrypt_key` or `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#encrypt_key` (only when the original key is recoverable)
▾
Generate a new API key while preserving the configuration from an existing key.
This operation creates a fresh key with a new token while maintaining all settings from the original key:
- Permissions and roles
- Custom metadata
- Rate limit configurations
- Identity associations
- Remaining credits
- Recovery settings
**Key Generation:**
- The system attempts to extract the prefix from the original key
- If prefix extraction fails, the default API prefix is used
- Key length follows the API's default byte configuration (or 16 bytes if not specified)
**Original Key Handling:**
- The original key will be revoked after the duration specified in `expiration`
- Set `expiration` to 0 to revoke immediately
- This allows for graceful key rotation with an overlap period
Common use cases include:
- Rotating keys for security compliance
- Issuing replacement keys for compromised credentials
- Creating backup keys with identical permissions
**Important:** Analytics and usage metrics are tracked at both the key level AND identity level. If the original key has an identity, the new key will inherit it, allowing you to track usage across both individual keys and the overall identity.
**Required Permissions**
Your credential must have:
- `api.*.create_key` or `api.<api_id>.create_key`
- `unkey:v1:<workspace_id>:keyspaces/*#create_key` or `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>#create_key`
- `api.*.encrypt_key` or `api.<api_id>.encrypt_key` (only when the original key is recoverable)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#encrypt_key` or `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#encrypt_key` (only when the original key is recoverable)
Open-world
unkey_v2_liveness
Check if the Unkey API service is healthy and ready to handle requests.
Use this for load balancer health checks, monitoring systems, and orchestration platforms. No authentication required with minimal processing overhead.
**Required Permissions**
None - this endpoint requires no authentication.
**Side Effects**
None - this is a read-only health check that does not modify any data or state.
▾
Check if the Unkey API service is healthy and ready to handle requests.
Use this for load balancer health checks, monitoring systems, and orchestration platforms. No authentication required with minimal processing overhead.
**Required Permissions**
None - this endpoint requires no authentication.
**Side Effects**
None - this is a read-only health check that does not modify any data or state.
Read-only
Idempotent
Open-world
unkey_v2_keys_remove_roles
Remove roles from a key without affecting direct permissions or other roles.
Use this for privilege downgrades, removing temporary access, or subscription changes that revoke specific role-based capabilities. Direct permissions remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.
▾
Remove roles from a key without affecting direct permissions or other roles.
Use this for privilege downgrades, removing temporary access, or subscription changes that revoke specific role-based capabilities. Direct permissions remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.
Open-world
unkey_v2_keys_remove_permissions
Remove permissions from a key without affecting existing roles or other permissions.
Use this for privilege downgrades, removing temporary access, or plan changes that revoke specific capabilities. Permissions granted through roles remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.
▾
Remove permissions from a key without affecting existing roles or other permissions.
Use this for privilege downgrades, removing temporary access, or plan changes that revoke specific capabilities. Permissions granted through roles remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes permission changes available for verification within 30 seconds across all regions.
Open-world
unkey_v2_keys_get_key
Retrieve detailed key information for dashboard interfaces and administrative purposes.
Use this to build key management dashboards showing users their key details, status, permissions, and usage data. You can identify keys by `keyId` or the actual key string.
**Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.
**Required Permissions**
Your credential must have one of the following permissions for basic key information:
- `api.*.read_key` (to read keys from any API)
- `api.<api_id>.read_key` (to read keys from a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#read_key` (to read keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#read_key` (to read keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#read_key` (to read a specific key)
Additional permission required for decrypt functionality:
- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#decrypt_key`
▾
Retrieve detailed key information for dashboard interfaces and administrative purposes.
Use this to build key management dashboards showing users their key details, status, permissions, and usage data. You can identify keys by `keyId` or the actual key string.
**Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.
**Required Permissions**
Your credential must have one of the following permissions for basic key information:
- `api.*.read_key` (to read keys from any API)
- `api.<api_id>.read_key` (to read keys from a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#read_key` (to read keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#read_key` (to read keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#read_key` (to read a specific key)
Additional permission required for decrypt functionality:
- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#decrypt_key`
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#decrypt_key`
Open-world
unkey_v2_keys_delete_key
Delete API keys from user accounts or for cleanup purposes.
Use this for user-requested key revocation, account deletion workflows, or cleaning up unused keys. Keys are immediately invalidated. Two modes: soft delete (default, preserves audit records) and permanent delete.
**Important**: For temporary access control, use `updateKey` with `enabled: false` instead of deletion.
**Required Permissions**
Your credential must have one of the following permissions:
- `api.*.delete_key` (to delete keys in any API)
- `api.<api_id>.delete_key` (to delete keys in a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#delete_key` (to delete keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#delete_key` (to delete keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#delete_key` (to delete a specific key)
▾
Delete API keys from user accounts or for cleanup purposes.
Use this for user-requested key revocation, account deletion workflows, or cleaning up unused keys. Keys are immediately invalidated. Two modes: soft delete (default, preserves audit records) and permanent delete.
**Important**: For temporary access control, use `updateKey` with `enabled: false` instead of deletion.
**Required Permissions**
Your credential must have one of the following permissions:
- `api.*.delete_key` (to delete keys in any API)
- `api.<api_id>.delete_key` (to delete keys in a specific API)
- `unkey:v1:<workspace_id>:keyspaces/*/keys/*#delete_key` (to delete keys in any keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/*#delete_key` (to delete keys in a specific keyspace)
- `unkey:v1:<workspace_id>:keyspaces/<keyspace_id>/keys/<key_id>#delete_key` (to delete a specific key)
Open-world
unkey_v2_keys_add_roles
Add roles to a key without affecting existing roles or permissions.
Use this for privilege upgrades, enabling new feature sets, or subscription changes that grant additional role-based capabilities. Direct permissions remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes role assignments available for verification within 30 seconds across all regions.
▾
Add roles to a key without affecting existing roles or permissions.
Use this for privilege upgrades, enabling new feature sets, or subscription changes that grant additional role-based capabilities. Direct permissions remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes role assignments available for verification within 30 seconds across all regions.
Open-world
unkey_v2_deployments_create_deployment
Create a deployment for an app in a project.
Provide exactly one source:
- `image`: deploy a prebuilt Docker image as-is (no build).
- `git`: build and deploy from the app's connected GitHub repository, a branch, a specific commit, or a fork commit. Requires the app to have a repository connected.
- `deployment`: re-run an existing deployment by its id. Git-connected apps rebuild from the recorded commit; other apps reuse the recorded image.
Returns immediately with a `deploymentId`. The build and rollout run asynchronously — poll `deployments.getDeployment` to watch status until it is ready.
**Authentication**: requires a root key with permission to create deployments.
▾
Create a deployment for an app in a project.
Provide exactly one source:
- `image`: deploy a prebuilt Docker image as-is (no build).
- `git`: build and deploy from the app's connected GitHub repository, a branch, a specific commit, or a fork commit. Requires the app to have a repository connected.
- `deployment`: re-run an existing deployment by its id. Git-connected apps rebuild from the recorded commit; other apps reuse the recorded image.
Returns immediately with a `deploymentId`. The build and rollout run asynchronously — poll `deployments.getDeployment` to watch status until it is ready.
**Authentication**: requires a root key with permission to create deployments.
Open-world
unkey_v2_keys_add_permissions
Add permissions to a key without affecting existing permissions.
Use this for privilege upgrades, enabling new features, or plan changes that grant additional capabilities. Permissions granted through roles remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes permissions available for verification within 30 seconds across all regions.
▾
Add permissions to a key without affecting existing permissions.
Use this for privilege upgrades, enabling new features, or plan changes that grant additional capabilities. Permissions granted through roles remain unchanged.
**Important**: Changes take effect immediately with up to 30-second edge propagation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.update_key` (to update keys in any API)
- `api.<api_id>.update_key` (to update keys in a specific API)
**Side Effects**
Invalidates the key cache for immediate effect, and makes permissions available for verification within 30 seconds across all regions.
Open-world
unkey_v2_identities_list_identities
Get a paginated list of all identities in your workspace. Returns metadata and rate limit configurations.
Perfect for building management dashboards, auditing configurations, or browsing your identities.
> **Important**
> Requires `identity.*.read_identity` permission
▾
Get a paginated list of all identities in your workspace. Returns metadata and rate limit configurations.
Perfect for building management dashboards, auditing configurations, or browsing your identities.
> **Important**
> Requires `identity.*.read_identity` permission
Open-world
unkey_v2_environments_remove_environment_variables
Remove environment variables from an environment in a single atomic request.
This operation only deletes keys by name. Keys in the payload that exist are
removed; keys that are not present are ignored, since their absence already
matches the requested state. To replace or update values, use
`setEnvironmentVariables` instead. The whole operation is atomic: if any part
fails the environment is left unchanged.
Duplicate keys in the payload collapse to a single removal. Values are never
read or returned.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.remove_environment_variables` (for any environment)
- `environment.<environment_id>.remove_environment_variables` (for a specific environment)
▾
Remove environment variables from an environment in a single atomic request.
This operation only deletes keys by name. Keys in the payload that exist are
removed; keys that are not present are ignored, since their absence already
matches the requested state. To replace or update values, use
`setEnvironmentVariables` instead. The whole operation is atomic: if any part
fails the environment is left unchanged.
Duplicate keys in the payload collapse to a single removal. Values are never
read or returned.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.remove_environment_variables` (for any environment)
- `environment.<environment_id>.remove_environment_variables` (for a specific environment)
Open-world
unkey_v2_environments_list_environment_variables
Retrieve the environment variables for an environment.
Identify the environment by its project, app, and environment identifiers.
Results are ordered by variable id and paginated; when `hasMore` is true,
pass the returned `cursor` to fetch the next page.
`recoverable` variables are returned with their decrypted plaintext value.
`writeonly` variables never expose a value: only the key, kind, and
description are returned.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_environment_variables` (for any environment)
- `environment.<environment_id>.read_environment_variables` (for a specific environment)
▾
Retrieve the environment variables for an environment.
Identify the environment by its project, app, and environment identifiers.
Results are ordered by variable id and paginated; when `hasMore` is true,
pass the returned `cursor` to fetch the next page.
`recoverable` variables are returned with their decrypted plaintext value.
`writeonly` variables never expose a value: only the key, kind, and
description are returned.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_environment_variables` (for any environment)
- `environment.<environment_id>.read_environment_variables` (for a specific environment)
Open-world
unkey_v2_apps_update_app
Update an existing app, identified by its id.
The app name, slug, default branch, and delete protection setting can be changed. Omitted fields are left unchanged. Changing the slug affects the deployment domains generated for this app.
**Important**: The slug cannot collide with an existing app in the same project. A duplicate slug returns a 409 conflict.
**Required Permissions**
Your root key must have one of the following permissions:
- `app.*.update_app` (to update any app)
- `app.<app_id>.update_app` (to update a specific app)
▾
Update an existing app, identified by its id.
The app name, slug, default branch, and delete protection setting can be changed. Omitted fields are left unchanged. Changing the slug affects the deployment domains generated for this app.
**Important**: The slug cannot collide with an existing app in the same project. A duplicate slug returns a 409 conflict.
**Required Permissions**
Your root key must have one of the following permissions:
- `app.*.update_app` (to update any app)
- `app.<app_id>.update_app` (to update a specific app)
Open-world
unkey_v2_domains_list_domains
List the custom domains attached to an environment and their verification status.
Results are paginated and sorted by their id. When `hasMore` is true, send the
returned `cursor` to get the next page. An environment with no domains returns an
empty array, not a 404.
`status: verified` means the domain is verified. Unkey has configured routing and requested a
certificate. Each domain includes its full `dnsRecords`. Each record has a `verified` flag.
The flag shows which records Unkey has read back, so you can see which records are still
missing without a second call. Some providers hide a record from DNS lookups, for example a
proxied or flattened routing record. Such a record stays `false` while it serves traffic.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_domain` (to read domains in any environment)
- `environment.<environment_id>.read_domain` (to read domains in a specific environment)
▾
List the custom domains attached to an environment and their verification status.
Results are paginated and sorted by their id. When `hasMore` is true, send the
returned `cursor` to get the next page. An environment with no domains returns an
empty array, not a 404.
`status: verified` means the domain is verified. Unkey has configured routing and requested a
certificate. Each domain includes its full `dnsRecords`. Each record has a `verified` flag.
The flag shows which records Unkey has read back, so you can see which records are still
missing without a second call. Some providers hide a record from DNS lookups, for example a
proxied or flattened routing record. Such a record stays `false` while it serves traffic.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_domain` (to read domains in any environment)
- `environment.<environment_id>.read_domain` (to read domains in a specific environment)
Open-world
unkey_v2_identities_get_identity
Retrieve an identity by external ID. Returns metadata, rate limits, and other associated data.
Use this to check if an identity exists, view configurations, or build management dashboards.
> **Important**
> Requires `identity.*.read_identity` permission
▾
Retrieve an identity by external ID. Returns metadata, rate limits, and other associated data.
Use this to check if an identity exists, view configurations, or build management dashboards.
> **Important**
> Requires `identity.*.read_identity` permission
Open-world
unkey_v2_gateway_list_policies
Retrieve an environment's gateway policies in evaluation order: the
gateway evaluates them top to bottom and the first rejection
short-circuits the request.
The full policy list is returned in a single response.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_policies` (for any environment)
- `environment.<environment_id>.read_policies` (for a specific environment)
▾
Retrieve an environment's gateway policies in evaluation order: the
gateway evaluates them top to bottom and the first rejection
short-circuits the request.
The full policy list is returned in a single response.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_policies` (for any environment)
- `environment.<environment_id>.read_policies` (for a specific environment)
Open-world
unkey_v2_identities_delete_identity
Permanently delete an identity. This operation cannot be undone.
Use this for data cleanup, compliance requirements, or when removing entities from your system.
> **Important**
> Requires `identity.*.delete_identity` permission
> Associated API keys remain functional but lose shared resources
> External ID becomes available for reuse immediately
▾
Permanently delete an identity. This operation cannot be undone.
Use this for data cleanup, compliance requirements, or when removing entities from your system.
> **Important**
> Requires `identity.*.delete_identity` permission
> Associated API keys remain functional but lose shared resources
> External ID becomes available for reuse immediately
Open-world
unkey_v2_environments_get_environment
Retrieve a single environment by its id.
Use this to fetch environment details after creation or to verify an environment exists before performing operations.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_environment` (to read any environment)
- `environment.<environment_id>.read_environment` (to read a specific environment)
▾
Retrieve a single environment by its id.
Use this to fetch environment details after creation or to verify an environment exists before performing operations.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_environment` (to read any environment)
- `environment.<environment_id>.read_environment` (to read a specific environment)
Open-world
unkey_v2_deployments_list_deployments
Retrieve a paginated list of deployments within a workspace, newest first.
Filter by project, app, environment, and lifecycle status. All filters are
optional; with none set, every deployment in the workspace is returned.
Filters nest: `app` requires `project`, and `environment` requires both
`project` and `app`. Results are paginated; when `hasMore` is true, pass the
returned `cursor` to fetch the next page.
**Required Permissions**
Your root key must have the `environment.*.read_deployment` permission.
Listing spans environments, so a grant on a single environment is not
sufficient.
▾
Retrieve a paginated list of deployments within a workspace, newest first.
Filter by project, app, environment, and lifecycle status. All filters are
optional; with none set, every deployment in the workspace is returned.
Filters nest: `app` requires `project`, and `environment` requires both
`project` and `app`. Results are paginated; when `hasMore` is true, pass the
returned `cursor` to fetch the next page.
**Required Permissions**
Your root key must have the `environment.*.read_deployment` permission.
Listing spans environments, so a grant on a single environment is not
sufficient.
Open-world
unkey_v2_environments_list_environments
Retrieve the environments within an app.
Use this to enumerate every environment in an app. Identify the app by its project slug and app slug. Results are ordered by environment id. An app has only a handful of environments, so all of them are returned in a single response.
**Required Permissions**
Your root key must have the following permission:
- `environment.*.read_environment` (to read environments in any app)
▾
Retrieve the environments within an app.
Use this to enumerate every environment in an app. Identify the app by its project slug and app slug. Results are ordered by environment id. An app has only a handful of environments, so all of them are returned in a single response.
**Required Permissions**
Your root key must have the following permission:
- `environment.*.read_environment` (to read environments in any app)
Open-world
unkey_v2_domains_create_domain
Attach a custom domain to an environment and start verifying it.
The domain is created in the `pending` state and does not serve traffic until verification succeeds. Verification runs in the background and polls DNS, so it is eventually consistent.
The response returns `dnsRecords`: every record needed to finish setup, already resolved for whether this domain is an apex or a subdomain. Create every entry exactly as given. One record establishes routing and one proves ownership, and both are needed: whether ownership can be inferred from the routing record depends on how your provider publishes it, and a name another workspace has already verified can only be claimed through the ownership record. Neither is knowable before the records exist.
When your DNS provider supports Domain Connect, the response also carries a `domainConnect` object; opening its `url` applies the same records at the provider in one step. The object is absent when the shortcut is unavailable.
Domains are unique per workspace, so the same name cannot be attached to two environments. Attaching a domain that already exists in your workspace returns a 409 conflict.
How many domains you may attach is set by your plan. Attaching one beyond that allowance returns a 403; upgrade the plan or remove a domain you no longer need.
**Important**: verification stops after 24 hours without the required DNS records, and the domain moves to `failed`.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.create_domain` (to attach domains to any environment)
- `environment.<environment_id>.create_domain` (to attach domains to a specific environment)
▾
Attach a custom domain to an environment and start verifying it.
The domain is created in the `pending` state and does not serve traffic until verification succeeds. Verification runs in the background and polls DNS, so it is eventually consistent.
The response returns `dnsRecords`: every record needed to finish setup, already resolved for whether this domain is an apex or a subdomain. Create every entry exactly as given. One record establishes routing and one proves ownership, and both are needed: whether ownership can be inferred from the routing record depends on how your provider publishes it, and a name another workspace has already verified can only be claimed through the ownership record. Neither is knowable before the records exist.
When your DNS provider supports Domain Connect, the response also carries a `domainConnect` object; opening its `url` applies the same records at the provider in one step. The object is absent when the shortcut is unavailable.
Domains are unique per workspace, so the same name cannot be attached to two environments. Attaching a domain that already exists in your workspace returns a 409 conflict.
How many domains you may attach is set by your plan. Attaching one beyond that allowance returns a 403; upgrade the plan or remove a domain you no longer need.
**Important**: verification stops after 24 hours without the required DNS records, and the domain moves to `failed`.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.create_domain` (to attach domains to any environment)
- `environment.<environment_id>.create_domain` (to attach domains to a specific environment)
Open-world
unkey_v2_github_install_app
Start installing the Unkey GitHub App for your workspace. Returns a GitHub
App install URL: open it in a browser to install the app and grant
repository access. After installation GitHub returns to Unkey, which binds
the installation to your workspace and lands you in the workspace settings.
Installation is workspace-wide and takes no parameters. Once installed, link
repositories to individual apps with the `git` field on `apps.createApp` and
`apps.updateApp`.
**Required Permissions**
Your root key must have the following permission:
- `workspace.*.install_github`
▾
Start installing the Unkey GitHub App for your workspace. Returns a GitHub
App install URL: open it in a browser to install the app and grant
repository access. After installation GitHub returns to Unkey, which binds
the installation to your workspace and lands you in the workspace settings.
Installation is workspace-wide and takes no parameters. Once installed, link
repositories to individual apps with the `git` field on `apps.createApp` and
`apps.updateApp`.
**Required Permissions**
Your root key must have the following permission:
- `workspace.*.install_github`
Open-world
unkey_v2_apps_create_app
Create an app within a project. The app is created with default `production` and `preview` environments.
The slug you provide is the stable, caller-defined handle used to reference this app. It must be unique within the project.
**Important**: The slug cannot collide with an existing app in the same project. A duplicate slug returns a 409 conflict.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.create_app` (to create apps in any project)
- `project.<project_id>.create_app` (to create apps in a specific project)
▾
Create an app within a project. The app is created with default `production` and `preview` environments.
The slug you provide is the stable, caller-defined handle used to reference this app. It must be unique within the project.
**Important**: The slug cannot collide with an existing app in the same project. A duplicate slug returns a 409 conflict.
**Required Permissions**
Your root key must have one of the following permissions:
- `project.*.create_app` (to create apps in any project)
- `project.<project_id>.create_app` (to create apps in a specific project)
Open-world
unkey_v2_domains_verify_domain
Restart verification for a custom domain.
Address the domain by its ID or by its name. Names are unique per workspace, so
`api.acme.com` is enough.
Call this after you correct the DNS records of a domain that shows `failed`, or to give a
`pending` domain a new 24-hour verification period. The domain goes back to `pending` and
the 24-hour period starts again.
The endpoint returns when Unkey accepts the retry. Poll `domains.getDomain` for the result.
A domain that is already `verified` returns a 412.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.verify_domain` (to verify domains in any environment)
- `environment.<environment_id>.verify_domain` (to verify domains in a specific environment)
▾
Restart verification for a custom domain.
Address the domain by its ID or by its name. Names are unique per workspace, so
`api.acme.com` is enough.
Call this after you correct the DNS records of a domain that shows `failed`, or to give a
`pending` domain a new 24-hour verification period. The domain goes back to `pending` and
the 24-hour period starts again.
The endpoint returns when Unkey accepts the retry. Poll `domains.getDomain` for the result.
A domain that is already `verified` returns a 412.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.verify_domain` (to verify domains in any environment)
- `environment.<environment_id>.verify_domain` (to verify domains in a specific environment)
Open-world
unkey_v2_apis_list_keys
Retrieve a paginated list of API keys for dashboard and administrative interfaces.
Use this to build key management dashboards, filter keys by user with `externalId`, or retrieve key details for administrative purposes. Each key includes status, metadata, permissions, and usage limits.
**Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.
**Required Permissions**
Your root key must have one of the following permissions for basic key listing:
- `api.*.read_key` (to read keys from any API)
- `api.<api_id>.read_key` (to read keys from a specific API)
Additionally, you need read access to the API itself:
- `api.*.read_api` or `api.<api_id>.read_api`
Additional permission required for decrypt functionality:
- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
▾
Retrieve a paginated list of API keys for dashboard and administrative interfaces.
Use this to build key management dashboards, filter keys by user with `externalId`, or retrieve key details for administrative purposes. Each key includes status, metadata, permissions, and usage limits.
**Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.
**Required Permissions**
Your root key must have one of the following permissions for basic key listing:
- `api.*.read_key` (to read keys from any API)
- `api.<api_id>.read_key` (to read keys from a specific API)
Additionally, you need read access to the API itself:
- `api.*.read_api` or `api.<api_id>.read_api`
Additional permission required for decrypt functionality:
- `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
Open-world
unkey_v2_domains_delete_domain
Delete a custom domain from your workspace.
Address the domain by its id or by its name. Names are unique per workspace, so
`api.acme.com` is enough.
Unkey stops serving the domain. Later requests fail with a certificate error. The DNS
records at your provider stay in place.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.delete_domain` (to delete domains in any environment)
- `environment.<environment_id>.delete_domain` (to delete domains in a specific environment)
▾
Delete a custom domain from your workspace.
Address the domain by its id or by its name. Names are unique per workspace, so
`api.acme.com` is enough.
Unkey stops serving the domain. Later requests fail with a certificate error. The DNS
records at your provider stay in place.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.delete_domain` (to delete domains in any environment)
- `environment.<environment_id>.delete_domain` (to delete domains in a specific environment)
Open-world
unkey_v2_deployments_stop_deployment
Stop a running preview deployment. Stopped deployments keep their
configuration and can be resumed later with `startDeployment`.
The deployment must be ready and running, and must belong to a
non-production environment; production deployments cannot be stopped.
A deployment that is already draining from a previous stop is rejected
with a precondition error.
Stopping is asynchronous: this endpoint only enqueues the stop and returns
immediately. Poll `getDeployment` until the status reaches `stopped`.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.stop_deployment` (to stop deployments in any environment)
- `environment.<environment_id>.stop_deployment` (to stop deployments in a specific environment)
▾
Stop a running preview deployment. Stopped deployments keep their
configuration and can be resumed later with `startDeployment`.
The deployment must be ready and running, and must belong to a
non-production environment; production deployments cannot be stopped.
A deployment that is already draining from a previous stop is rejected
with a precondition error.
Stopping is asynchronous: this endpoint only enqueues the stop and returns
immediately. Poll `getDeployment` until the status reaches `stopped`.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.stop_deployment` (to stop deployments in any environment)
- `environment.<environment_id>.stop_deployment` (to stop deployments in a specific environment)
Open-world
unkey_v2_apps_list_apps
Retrieve a paginated list of apps within a project.
Use this to enumerate every app in a project. Results are ordered by app id and paginated; when `hasMore` is true, pass the returned `cursor` to fetch the next page.
**Required Permissions**
Your root key must have the following permission:
- `app.*.read_app` (to read apps in any project)
▾
Retrieve a paginated list of apps within a project.
Use this to enumerate every app in a project. Results are ordered by app id and paginated; when `hasMore` is true, pass the returned `cursor` to fetch the next page.
**Required Permissions**
Your root key must have the following permission:
- `app.*.read_app` (to read apps in any project)
Open-world
unkey_v2_domains_get_domain
Retrieve a custom domain and its verification status.
Address the domain by its id or by its name. Names are unique per workspace, so
`api.acme.com` is sufficient. You do not need to supply a project, app, or environment.
Use this endpoint to poll after `domains.createDomain`. Verification runs in the background
and checks DNS approximately each minute.
`status: verified` means the domain is verified. Unkey has configured routing and requested a
certificate. Each entry in `dnsRecords` has a `verified` flag. The flag shows which records
Unkey has read back, so you can see which records are still missing. Some providers hide a
record from DNS lookups, for example a proxied or flattened routing record. Such a record stays
`false` while it serves traffic. `verificationError` gives the reason for the last failed
attempt.
`dnsRecords` contains the same values that `domains.createDomain` returned. Use it to recover
the values without creating the domain again.
**Important**: verification stops 24 hours after the domain was created, and the status becomes
`failed`. The window starts at `createdAt`, not at the last attempt.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_domain` (to read domains in any environment)
- `environment.<environment_id>.read_domain` (to read domains in a specific environment)
▾
Retrieve a custom domain and its verification status.
Address the domain by its id or by its name. Names are unique per workspace, so
`api.acme.com` is sufficient. You do not need to supply a project, app, or environment.
Use this endpoint to poll after `domains.createDomain`. Verification runs in the background
and checks DNS approximately each minute.
`status: verified` means the domain is verified. Unkey has configured routing and requested a
certificate. Each entry in `dnsRecords` has a `verified` flag. The flag shows which records
Unkey has read back, so you can see which records are still missing. Some providers hide a
record from DNS lookups, for example a proxied or flattened routing record. Such a record stays
`false` while it serves traffic. `verificationError` gives the reason for the last failed
attempt.
`dnsRecords` contains the same values that `domains.createDomain` returned. Use it to recover
the values without creating the domain again.
**Important**: verification stops 24 hours after the domain was created, and the status becomes
`failed`. The window starts at `createdAt`, not at the last attempt.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_domain` (to read domains in any environment)
- `environment.<environment_id>.read_domain` (to read domains in a specific environment)
Open-world
unkey_v2_deployments_start_deployment
Start a deployment that was previously stopped with `stopDeployment`, so it
serves traffic again. The deployment keeps the configuration it had when it
was stopped; nothing is rebuilt or redeployed.
The deployment must currently be stopped, and must belong to a
non-production environment. Production deployments are never stopped, so
they cannot be started.
Starting is asynchronous: this endpoint only enqueues the start and returns
immediately. Poll `getDeployment` until the status reaches `ready`.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.start_deployment` (to start deployments in any environment)
- `environment.<environment_id>.start_deployment` (to start deployments in a specific environment)
▾
Start a deployment that was previously stopped with `stopDeployment`, so it
serves traffic again. The deployment keeps the configuration it had when it
was stopped; nothing is rebuilt or redeployed.
The deployment must currently be stopped, and must belong to a
non-production environment. Production deployments are never stopped, so
they cannot be started.
Starting is asynchronous: this endpoint only enqueues the start and returns
immediately. Poll `getDeployment` until the status reaches `ready`.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.start_deployment` (to start deployments in any environment)
- `environment.<environment_id>.start_deployment` (to start deployments in a specific environment)
Open-world
unkey_v2_deployments_promote_deployment
Promote a deployment to become the current deployment for its environment.
All sticky domains are reassigned from the current deployment to the
promoted one, and the previous deployment is scheduled for standby.
The deployment must be ready, not already shutting down, belong to the
production environment, and its app must already have a current deployment.
Promoting the deployment that is already current fails, unless the app is in
a rolled-back state, in which case promoting the current deployment
confirms the rollback and re-enables automatic promotion of future
deployments.
Promotion runs as a durable workflow: this endpoint returns once the
promotion is accepted. Poll `getDeployment` or `listDeployments` to observe
the result.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.promote_deployment` (to promote deployments in any environment)
- `environment.<environment_id>.promote_deployment` (to promote deployments in a specific environment)
▾
Promote a deployment to become the current deployment for its environment.
All sticky domains are reassigned from the current deployment to the
promoted one, and the previous deployment is scheduled for standby.
The deployment must be ready, not already shutting down, belong to the
production environment, and its app must already have a current deployment.
Promoting the deployment that is already current fails, unless the app is in
a rolled-back state, in which case promoting the current deployment
confirms the rollback and re-enables automatic promotion of future
deployments.
Promotion runs as a durable workflow: this endpoint returns once the
promotion is accepted. Poll `getDeployment` or `listDeployments` to observe
the result.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.promote_deployment` (to promote deployments in any environment)
- `environment.<environment_id>.promote_deployment` (to promote deployments in a specific environment)
Open-world
unkey_v2_deployments_rollback_deployment
Roll live traffic back to a previous deployment. `deploymentId` is the
deployment to roll back TO; the app's current deployment is used as
the rollback source automatically.
The target deployment must be ready, not already shutting down, belong to
the production environment, and must not itself be the current deployment.
After a rollback the app is marked as rolled back, which prevents new
deployments from automatically taking over live traffic. Promote the
rolled-back deployment (or a newer one) to clear this state.
Rollback runs as a durable workflow: this endpoint returns once the
rollback is accepted. Poll `getDeployment` or `listDeployments` to observe
the result.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.rollback_deployment` (to roll back deployments in any environment)
- `environment.<environment_id>.rollback_deployment` (to roll back deployments in a specific environment)
▾
Roll live traffic back to a previous deployment. `deploymentId` is the
deployment to roll back TO; the app's current deployment is used as
the rollback source automatically.
The target deployment must be ready, not already shutting down, belong to
the production environment, and must not itself be the current deployment.
After a rollback the app is marked as rolled back, which prevents new
deployments from automatically taking over live traffic. Promote the
rolled-back deployment (or a newer one) to clear this state.
Rollback runs as a durable workflow: this endpoint returns once the
rollback is accepted. Poll `getDeployment` or `listDeployments` to observe
the result.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.rollback_deployment` (to roll back deployments in any environment)
- `environment.<environment_id>.rollback_deployment` (to roll back deployments in a specific environment)
Open-world
unkey_v2_apps_delete_app
Delete an existing app, identified by its id.
Deletion is asynchronous and eventually consistent. The app and all of its associated resources (environments, deployments, custom domains) are torn down by a background workflow. A successful response indicates the deletion was enqueued, not that every resource has already been removed.
Apps with delete protection enabled cannot be deleted until protection is disabled.
**Required Permissions**
Your root key must have one of the following permissions:
- `app.*.delete_app` (to delete any app)
- `app.<app_id>.delete_app` (to delete a specific app)
▾
Delete an existing app, identified by its id.
Deletion is asynchronous and eventually consistent. The app and all of its associated resources (environments, deployments, custom domains) are torn down by a background workflow. A successful response indicates the deletion was enqueued, not that every resource has already been removed.
Apps with delete protection enabled cannot be deleted until protection is disabled.
**Required Permissions**
Your root key must have one of the following permissions:
- `app.*.delete_app` (to delete any app)
- `app.<app_id>.delete_app` (to delete a specific app)
Open-world
unkey_v2_apps_get_app
Retrieve a single app by its id or slug within a project.
Use this to fetch app details after creation or to verify an app exists before performing operations.
**Required Permissions**
Your root key must have one of the following permissions:
- `app.*.read_app` (to read any app)
- `app.<app_id>.read_app` (to read a specific app)
▾
Retrieve a single app by its id or slug within a project.
Use this to fetch app details after creation or to verify an app exists before performing operations.
**Required Permissions**
Your root key must have one of the following permissions:
- `app.*.read_app` (to read any app)
- `app.<app_id>.read_app` (to read a specific app)
Open-world
unkey_v2_deployments_get_deployment
Retrieve a single deployment by its id.
Use this to check a deployment's status after creating it, or to inspect the
runtime configuration of an existing deployment.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_deployment` (to read deployments in any environment)
- `environment.<environment_id>.read_deployment` (to read deployments in a specific environment)
▾
Retrieve a single deployment by its id.
Use this to check a deployment's status after creating it, or to inspect the
runtime configuration of an existing deployment.
**Required Permissions**
Your root key must have one of the following permissions:
- `environment.*.read_deployment` (to read deployments in any environment)
- `environment.<environment_id>.read_deployment` (to read deployments in a specific environment)
Open-world
unkey_v2_apis_delete_api
Permanently delete an API namespace and immediately invalidate all associated keys.
Use this for cleaning up development environments, retiring deprecated services, or removing unused resources.
All keys in the namespace are immediately marked as deleted and will fail verification with `code=NOT_FOUND`.
**Important**: This operation is immediate and permanent. Verify you have the correct API ID before deletion.
If delete protection is enabled, disable it first through the dashboard or API configuration.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.delete_api` (to delete any API)
- `api.<api_id>.delete_api` (to delete a specific API)
▾
Permanently delete an API namespace and immediately invalidate all associated keys.
Use this for cleaning up development environments, retiring deprecated services, or removing unused resources.
All keys in the namespace are immediately marked as deleted and will fail verification with `code=NOT_FOUND`.
**Important**: This operation is immediate and permanent. Verify you have the correct API ID before deletion.
If delete protection is enabled, disable it first through the dashboard or API configuration.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.delete_api` (to delete any API)
- `api.<api_id>.delete_api` (to delete a specific API)
Open-world
unkey_v2_apis_get_api
Retrieve basic information about an API namespace including its ID and name.
Use this to verify an API exists before performing operations, get the human-readable name when you only have the API ID, or confirm access to a specific namespace. For detailed key information, use the `listKeys` endpoint instead.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.read_api` (to read any API)
- `api.<api_id>.read_api` (to read a specific API)
▾
Retrieve basic information about an API namespace including its ID and name.
Use this to verify an API exists before performing operations, get the human-readable name when you only have the API ID, or confirm access to a specific namespace. For detailed key information, use the `listKeys` endpoint instead.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.read_api` (to read any API)
- `api.<api_id>.read_api` (to read a specific API)
Open-world
unkey_v2_apis_create_api
Create an API namespace for organizing keys by environment, service, or product.
Use this to separate production from development keys, isolate different services, or manage multiple products. Each API gets a unique identifier and dedicated infrastructure for secure key operations.
**Important**: API names must be unique within your workspace and cannot be changed after creation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.create_api` (to create APIs in any workspace)
▾
Create an API namespace for organizing keys by environment, service, or product.
Use this to separate production from development keys, isolate different services, or manage multiple products. Each API gets a unique identifier and dedicated infrastructure for secure key operations.
**Important**: API names must be unique within your workspace and cannot be changed after creation.
**Required Permissions**
Your root key must have one of the following permissions:
- `api.*.create_api` (to create APIs in any workspace)
Open-world
unkey_v2_analytics_get_gateway_requests
A query can use only the public alias `gateway_requests_v1`. CTEs, subqueries, UNION, and EXCEPT are permitted.
The root key must have the `project.*.read_gateway_requests` permission.
Unkey limits each query to the workspace of the root key. To get the data for one project, app, or environment, add a filter on `project_id`, `app_id`, or `environment_id`.
The workspace retention period and the workspace query limits apply.
For the columns and more query examples, see the gateway request analytics documentation.
▾
A query can use only the public alias `gateway_requests_v1`. CTEs, subqueries, UNION, and EXCEPT are permitted.
The root key must have the `project.*.read_gateway_requests` permission.
Unkey limits each query to the workspace of the root key. To get the data for one project, app, or environment, add a filter on `project_id`, `app_id`, or `environment_id`.
The workspace retention period and the workspace query limits apply.
For the columns and more query examples, see the gateway request analytics documentation.
Open-world
unkey_v2_analytics_get_ratelimits
Queries may reference only the five public rate limit analytics aliases: `ratelimits_v1`, `ratelimits_per_minute_v1`, `ratelimits_per_hour_v1`, `ratelimits_per_day_v1`, or `ratelimits_per_month_v1`. CTEs, subqueries, UNION, and EXCEPT are supported.
Queries are always restricted to the authenticated workspace. Wildcard analytics permission can read every namespace in that workspace; namespace-scoped permissions automatically restrict results to the permitted namespace IDs.
Workspace retention and query limits apply.
▾
Queries may reference only the five public rate limit analytics aliases: `ratelimits_v1`, `ratelimits_per_minute_v1`, `ratelimits_per_hour_v1`, `ratelimits_per_day_v1`, or `ratelimits_per_month_v1`. CTEs, subqueries, UNION, and EXCEPT are supported.
Queries are always restricted to the authenticated workspace. Wildcard analytics permission can read every namespace in that workspace; namespace-scoped permissions automatically restrict results to the permitted namespace IDs.
Workspace retention and query limits apply.
Open-world
unkey_v2_analytics_get_verifications
Execute custom SQL queries against your key verification analytics. CTEs, subqueries, UNION, and EXCEPT are supported.
Queries must use one of the five public aliases: `key_verifications_v1`, `key_verifications_per_minute_v1`, `key_verifications_per_hour_v1`, `key_verifications_per_day_v1`, or `key_verifications_per_month_v1`. Physical `default.*` table names are unsupported.
Queries are always restricted to the authenticated workspace. Wildcard analytics permission can read every API in that workspace; API-scoped permissions automatically restrict results to the permitted APIs.
For complete documentation including available tables, columns, data types, query examples, see the schema reference in the API documentation.
▾
Execute custom SQL queries against your key verification analytics. CTEs, subqueries, UNION, and EXCEPT are supported.
Queries must use one of the five public aliases: `key_verifications_v1`, `key_verifications_per_minute_v1`, `key_verifications_per_hour_v1`, `key_verifications_per_day_v1`, or `key_verifications_per_month_v1`. Physical `default.*` table names are unsupported.
Queries are always restricted to the authenticated workspace. Wildcard analytics permission can read every API in that workspace; API-scoped permissions automatically restrict results to the permitted APIs.
For complete documentation including available tables, columns, data types, query examples, see the schema reference in the API documentation.
Open-world
unkey_v2_analytics_get_runtime_logs
A query can use only the public alias `runtime_logs_v1`. CTEs, subqueries, UNION, and EXCEPT are permitted.
The root key must have the `project.*.read_runtime_logs` permission.
Unkey limits each query to the workspace of the root key. To get the logs of one project, app, environment, or deployment, add a filter on `project_id`, `app_id`, `environment_id`, or `deployment_id`.
The workspace retention period and the workspace query limits apply.
For the table, the columns, and more query examples, see [Query runtime logs](/platform/analytics/get-runtime-logs).
▾
A query can use only the public alias `runtime_logs_v1`. CTEs, subqueries, UNION, and EXCEPT are permitted.
The root key must have the `project.*.read_runtime_logs` permission.
Unkey limits each query to the workspace of the root key. To get the logs of one project, app, environment, or deployment, add a filter on `project_id`, `app_id`, `environment_id`, or `deployment_id`.
The workspace retention period and the workspace query limits apply.
For the table, the columns, and more query examples, see [Query runtime logs](/platform/analytics/get-runtime-logs).
Open-world
No tools match your search.
https://mcp.unkey.com/mcp/v2
If you have a client that's not listed above, access the raw MCP
configuration below. Check out
the troubleshooting documentation
for more help.
{
"command": "npx",
"args": [
"mcp-remote@0.1.25",
"https://mcp.unkey.com/mcp/v2",
"--header",
"Mcp-Unkey-V2-Bearer:${UNKEY_ROOT_KEY}",
"--header",
"Mcp-Unkey-V2-Root-Key:${MCP_UNKEY_V2_ROOT_KEY}"
],
"env": {
"UNKEY_ROOT_KEY": "<your-value-here>",
"MCP_UNKEY_V2_ROOT_KEY": "<your-value-here>"
}
}