--- title: Unkey API Integration on Truto slug: unkey category: Application Development canonical: "https://truto.one/integrations/detail/unkey/" --- # Unkey API Integration on Truto **Category:** Application Development **Status:** Generally available ## MCP-ready AI tools Truto exposes 47 tools for Unkey that AI agents can call directly. - **unkey_analytics_get_verifications** — Execute a SELECT SQL query against key verification analytics in Unkey. Returns a meta object with requestId and a data array of verification rows whose fields match your SQL SELECT clause. Only SELECT queries are allowed. Required: query. - **create_a_unkey_api** — Create a new API namespace in Unkey. Returns the created namespace's api_id and request metadata. Required: name. - **delete_a_unkey_api_by_id** — Delete an Unkey API namespace by id. Returns request metadata and an empty data object on success. Required: id. - **get_single_unkey_api_by_id** — Get an Unkey API namespace by id. Returns the API namespace including id and name. Required: id. - **unkey_apis_list_keys** — List API keys for an Unkey API namespace. Returns: keyId, start, enabled, name, meta, createdAt, updatedAt, lastUsedAt, expires, permissions, roles, credits, identity, plaintext, ratelimits. Required: apiId. - **create_a_unkey_deployment** — Create a new deployment in Unkey from a pre-built Docker image. Returns the deployment id. Internal endpoint; not recommended for production use. Required: project, app, branch, environmentSlug, dockerImage. - **get_single_unkey_deployment_by_id** — Get deployment information in Unkey including status, error messages, and deployment steps. Returns: meta, data, id. Internal endpoint; not recommended for production use. Required: id. - **create_a_unkey_identity** — Create an identity in Unkey to group API keys under a single entity with shared metadata and rate limits. Returns the created identity with id, externalId, meta, and ratelimits, plus request metadata. Required: externalId. - **delete_a_unkey_identity_by_id** — Permanently delete an identity in Unkey. This operation cannot be undone. Returns only the request metadata (requestId). Required: id. - **get_single_unkey_identity_by_id** — Get an identity in Unkey by id. Returns the identity's id, externalId, meta, and ratelimits. Required: id. - **list_all_unkey_identities** — List identities in Unkey. Returns identities, a cursor, and a total count. Max 100 per page, defaults to 100. - **update_a_unkey_identity_by_id** — Update an identity's metadata and rate limits in Unkey. Only specified fields are modified. Returns the updated identity's id, externalId, meta, and ratelimits. Required: id. - **unkey_keys_add_permissions** — Add permissions to an Unkey key without replacing existing ones. Returns: id, name, slug, description. Required: keyId, permissions. - **unkey_keys_add_roles** — Add roles to an Unkey key without replacing existing roles or permissions. Returns: id, name, description, permissions. Required: keyId, roles. - **create_a_unkey_key** — Create a new Unkey API key. Returns: meta, data. The plaintext key is returned only once. Required: apiId. - **delete_a_unkey_key_by_id** — Delete an Unkey key by keyId. Returns: meta, data. Defaults to soft deletion. Required: id. - **get_single_unkey_key_by_id** — Get details of an Unkey key by id. Returns: meta, data. Required: id. - **unkey_keys_get_by_hash** — Look up an Unkey API key by its full key string. Returns meta and data; data contains the key record with keyId, enabled, name, permissions, roles, and credits. Required: key. - **unkey_keys_migrate** — Migrate pre-hashed API keys into an Unkey API. Returns meta and data; data contains the migration outcome with migrated entries (hash + keyId) and any failed hashes. Required: migrationId, apiId, keys. - **unkey_keys_remove_permissions** — Remove direct permissions from an Unkey key without affecting its roles. Returns meta and data; data lists the remaining direct permissions with id, name, slug, and description. Changes take up to 30 seconds to propagate. Required: keyId, permissions. - **unkey_keys_remove_roles** — Remove roles from an Unkey key without affecting its direct permissions. Returns meta and data; data lists the remaining roles with id, name, description, and permissions. Changes take up to 30 seconds to propagate. Required: keyId, roles. - **unkey_keys_reroll** — Generate a new Unkey API key while preserving an existing key's configuration. Returns meta and data; data contains the new keyId and key. Required: keyId, expiration. - **unkey_keys_set_permissions** — Replace all direct permissions on an Unkey key in one atomic operation. Returns meta and data: the updated permission list in data, including each permission's id, name, slug, and description. Changes may take up to 30 seconds to propagate across all edge regions. Required: keyId, permissions. - **unkey_keys_set_roles** — Replace all roles on an Unkey key in one atomic operation. Returns meta and data: the updated role list in data, including each role's id, name, description, and nested permissions. Changes may take up to 30 seconds to propagate across all edge regions. Required: keyId, roles. - **unkey_keys_update_credits** — Update a Unkey key's credit balance. Returns meta and data: the updated credit balance in data, including remaining and refill settings. Provide value when incrementing or decrementing; set value to null for unlimited credits. Required: keyId, operation. - **update_a_unkey_key_by_id** — Update an existing Unkey API key's settings. Supports partial updates such as name, metadata, expiration, credits, rate limits, roles, permissions, and enabled status. Returns meta and data: an empty data object confirming success. Changes take effect immediately but may take up to 30 seconds to propagate to all edge regions. Required: id. - **unkey_keys_verify** — Verify an Unkey API key's validity, permissions, rate limits, and usage quota for request authentication. Returns meta and data: the verification result including valid, keyId, name, meta, expires, credits, enabled, permissions, roles, identity, and ratelimits. Always returns HTTP 200; check the valid field to determine authorization. Required: key. - **unkey_keys_whoami** — Get information about an Unkey API key by its full key string. Returns the key object under `data` including keyId, start, enabled, createdAt, permissions, roles, credits, and ratelimits. Required: key. - **list_all_unkey_liveness** — Check the health status of the Unkey API. Returns the service health object including requestId, message, and response metadata. No authentication required. - **create_a_unkey_permission** — Create a new permission in Unkey. Returns the response envelope with meta and data containing permissionId. Required: name, slug. - **delete_a_unkey_permission_by_id** — Delete a permission in Unkey by permission id or slug. Returns the response envelope with meta and an empty data object on success. Required: id. - **get_single_unkey_permission_by_id** — Get a permission in Unkey by id or slug. Returns the response envelope with meta and data containing id, name, slug, and description. Required: id. - **list_all_unkey_permissions** — List all permissions in your Unkey workspace. Returns the response envelope with meta, an array of permission objects (id, name, slug, description), and pagination cursors. Optional: cursor, limit. - **update_a_unkey_permission_by_id** — Update a permission in unkey. Returns: meta, data, name, email, plan. Required: id. - **create_a_unkey_role** — Create a new role in Unkey. Returns: meta, data. Required: name. - **delete_a_unkey_role_by_id** — Delete a role in Unkey by role id or name. Returns meta and an empty data object. Required: id. - **get_single_unkey_role_by_id** — Get a role in Unkey by role id or name. Returns: meta, data. Required: id. - **list_all_unkey_roles** — List all roles in your Unkey workspace, including their assigned permissions. Returns: id, name, description, permissions. - **update_a_unkey_role_by_id** — Update an existing RBAC role in Unkey. Returns the updated role including id, name, description, and permissions. Required: id. Provide at least one of name, description, or permissions to change. - **unkey_ratelimit_limit** — Apply a single rate limit check in Unkey for an identifier within a namespace. Returns the rate limit result in data, including limit, remaining, reset, and success, plus request metadata in meta. Cost defaults to 1. Required: namespace, duration, identifier, limit. - **unkey_ratelimit_multi_limit** — Apply multiple rate limit checks in a single Unkey request. Returns the combined result in data, including a passed flag and per-check limits (limit, remaining, reset, success), plus request metadata in meta. - **unkey_ratelimit_set_override** — Create or update a custom Unkey rate limit override for an identifier pattern. Returns the override_id in data and request metadata in meta. Required: namespace, duration, identifier, limit. - **unkey_ratelimit_get_override** — Retrieve an existing Unkey rate limit override by namespace and identifier pattern. Returns the override configuration in data, including override_id, duration, identifier, and limit, plus request metadata in meta. Required: namespace, identifier. - **unkey_ratelimit_delete_override** — Delete an Unkey rate limit override by namespace and identifier pattern. Returns meta and an empty data object on success. Required: namespace, identifier. - **unkey_ratelimit_list_overrides** — List rate limit overrides in an Unkey namespace. Returns: overrideId, duration, identifier, limit. Required: namespace. - **unkey_portal_create_session** — Create a short-lived Unkey Portal session for an end user. Returns the session id, redirect URL, and request metadata. Requires slug, externalId, and permissions. - **unkey_portal_exchange_session** — Exchange a short-lived Unkey Portal session token for a long-lived browser session token. Returns the new token, its expiration timestamp, and request metadata. Requires sessionId. ## How it works 1. **Link your customer's Unkey account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Unkey.** The Proxy API is a 1-to-1 mapping of the Unkey API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Automate usage-based billing on API consumption** — Billing and monetization platforms can query verification analytics from their customers' Unkey workspaces to construct usage-based invoices, and disable keys instantly when payments fail. This removes the need to build a custom metering pipeline for every customer. - **Sync tenants and rate limits from your Auth/IdP** — Identity providers and B2B auth platforms can mirror their organization model into Unkey by provisioning identities and pushing rate limit overrides when plans change. This keeps edge-level gateway policy perfectly aligned with the customer's subscription state. - **Embed API key management inside developer docs** — Documentation platforms and developer portals can mint sandboxed keys on demand and drop a hosted Unkey management portal directly into their UI. End-developers get interactive 'Try It' functionality without the docs vendor building a full key management stack. - **Power prepaid credit and token top-ups for AI products** — AI platforms and API monetization tools can push credit balances directly onto their customers' Unkey keys after a top-up purchase. Credit enforcement happens at the edge, so the SaaS product avoids adding latency-heavy quota checks to every request. - **Deliver RBAC and permission provisioning to end customers** — Platforms managing developer workflows can programmatically create roles, permissions, and assign them to keys inside their users' Unkey accounts. This lets customers ship fine-grained access control on their APIs without building a permission engine. ## What you can build - **SQL-powered usage dashboards** — Run raw SELECT queries against Unkey's verification analytics to render request volumes, latency, and rejection breakdowns for each of your customers inside your product. - **Automatic key suspension on billing events** — Toggle `enabled: false` on specific keys the moment an invoice fails, a trial expires, or a customer is offboarded — enforced globally at the edge. - **Plan-tier rate limit sync** — Push rate limit overrides to specific identities whenever a customer upgrades, downgrades, or hits an abuse threshold in your SaaS. - **Credit top-up and metering** — Increment or decrement credit balances on individual keys in response to purchases, refunds, or manual grants from your admin panel. - **Embedded key management portal** — Generate short-lived Unkey portal sessions and redirect end-users into a white-labeled UI for creating, rotating, and revoking their keys — no dashboard build required. - **Tenant-to-identity provisioning** — Map your internal organization or workspace IDs to Unkey identities via `externalId`, so all keys under a tenant share rate limits and quotas automatically. ## FAQs ### How does authentication with a user's Unkey workspace work through Truto? Unkey uses root API keys scoped to a workspace. Truto handles secure storage and injection of these credentials on every request, so your product only needs to trigger the integration action — no token management on your side. ### Can we run analytics queries or is it limited to CRUD operations? Yes. The `unkey_analytics_get_verifications` tool accepts SQL SELECT queries against verification data, letting you aggregate request counts, latency, and rejection reasons on demand without ingesting webhooks. ### How do we manage rate limits per customer or tenant? Create an Unkey identity for each tenant using their internal ID as the `externalId`, then apply rate limit overrides via `unkey_ratelimit_set_override`. All keys under that identity share the same enforced limits at the edge. ### Can end-users manage their keys without us building a UI? Yes. Use `unkey_portal_create_session` to mint a short-lived session and redirect the user into Unkey's hosted portal for key creation, rotation, and revocation. ### How do we handle prepaid credits or quota top-ups? Call `unkey_keys_update_credits` with an increment or decrement value against a specific key. Unkey enforces the balance at the edge and rejects requests automatically when credits are depleted. ### What happens if we need to disable a customer's access immediately? Call `update_a_unkey_key_by_id` with `enabled: false` on the target keys. The change propagates across Unkey's edge network so subsequent verifications are rejected globally within milliseconds.