Glossary

Look up a term here. Terms that mean different things in different products come first, with each meaning labeled by product. The rest are grouped by the product that owns them.

Terms with more than one meaning

App

Compute. A service you deploy, inside a project. It has a GitHub repository or a container image as its source, two environments with their own build and runtime settings, and a history of deployments. On this site, “app” always means this. When we mean the software you run anywhere, including outside Unkey, we say “your application”. See Projects, apps, and environments.

Show in dashboard

Rate limiting

Four different features share this name:

• Platform: the limit on your workspace’s requests to the Unkey API. Going over it returns a 429 with err:user:too_many_requests:workspace_rate_limited. See Too many requests.
• API Management: the standalone ratelimit API. You call ratelimit.limit or ratelimit.multiLimit with a namespace, your own identifier, a limit, and a duration, and get back whether the request is allowed. See Rate limiting.
• API Management: key and identity rate limits. They’re attached to a key or an identity and checked when the key is verified, either automatically or when the verification request names them. The gateway key-auth policy can check them too. See Key and identity rate limits.
• Compute: the gateway rate limit policy. The gateway applies it to matching requests and rejects those over the limit before they reach your app. See Rate limit policy.

Role

Two different features share this name:

• Platform: a dashboard user’s role in a workspace, admin or developer. Developers can work with every resource in the workspace except root keys and portal sessions. Admins can also manage members, rename the workspace, manage root keys and portal sessions, set the spend budget, and change billing. See Team.
• API Management: a named group of permissions you attach to keys, so verification can check what a key’s holder is allowed to do. See Roles and permissions.

Show in dashboard

Verify

Three different features share this name:

• API Management: key verification with keys.verifyKey. You send a key, and we tell you whether it’s valid and, if not, why. See Verifying keys.
• Compute: custom domain verification, where you prove you control a domain before the gateway serves it. See Custom domains.
• Compute: the gateway key-auth policy, which verifies keys on the requests it applies to before they reach your app. See API key authentication policy.

Platform

Audit log

A record of every change made through the API or the dashboard: who made it, what changed, and from which IP. Nobody can edit or delete entries. Reads aren’t logged, except key verifications and rate limit checks made with a root key. See Audit logs.

Show in dashboard

CLI session

What unkey login creates. You sign in through your browser and choose which permissions the CLI gets. The session is stored in your system keychain. You can see and revoke sessions under Settings > CLI sessions, or end one with unkey logout. See CLI authentication.

Show in dashboard

Delete protection

A setting on keyspaces, projects, and apps that blocks deletion while it’s on. Deleting a protected resource through the API returns HTTP 412 with err:unkey:application:protected_resource. See Delete protection.

Show in dashboard

Limits

Your workspace’s ceilings, shown under Settings > Limits: monthly API operations, API requests per minute, log and audit log retention, log drains, and Compute resources. Compute limits cover CPU, memory, and disk for the workspace and per instance, concurrent builds, replicas per region, and custom domains. Most come from your API Management and Compute plans. Log drains and API requests per minute aren’t set by a plan. See Limits.

Show in dashboard

Log drain

Forwards one stream of workspace events to your own HTTPS endpoint or Axiom dataset. The streams are audit logs, key verifications, gateway HTTP requests, runtime logs, and rate limits. Every plan starts with a limit of 0 log drains, so ask support to turn them on. See Log drains.

Show in dashboard

Plan

What you pay for in each product. API Management starts on the free plan, with paid plans for higher limits. Compute plans are Starter, Pro, and Business. The two are billed separately to the same payment method, and you can have either without the other. See Plans.

Show in dashboard

Root key

The credential for calling the Unkey API. A root key belongs to one workspace and has a list of permissions. We store it hashed, so it’s shown only once, when you create it. The CLI usually signs in through your browser with unkey login instead, and uses a root key in CI. See Root keys.

Show in dashboard

Workspace

The top-level container for everything else. It has a slug used in dashboard URLs, a ws_ ID used in the API, and its own team, billing, and limits. Workspaces are fully separate from each other. See Workspaces.

Show in dashboard

Workspace rate limit

The limit on your workspace’s requests to the Unkey API, shown as API requests per minute under Settings > Limits. See the Platform meaning under Rate limiting.

API Management

Credits and refill

The number of uses a key has left. Each verification deducts a cost, 1 by default, that you can set per request. A key with no credits set has unlimited uses. Credits can refill daily or monthly. When the cost is more than what’s left, verification fails with USAGE_EXCEEDED. See Credits and refill.

Show in dashboard

Identity

One of your users or tenants, identified by your own externalId, that several keys can belong to. Rate limits on an identity are shared by all of its keys. If a key has its own limit with the same name, the key’s limit is used instead. See Identities.

Show in dashboard

Key

A credential you give to a user of your application and verify on each request. A key can have a prefix, a name, metadata, an expiry, credits, rate limits, permissions and roles, and an identity, and can be disabled. We always store its hash, plus a short start and end of the key for display. A recoverable key also has an encrypted copy. See Creating keys.

Show in dashboard

Keyspace

A container for API keys, called an API in endpoint names (apis.createApi). Each key belongs to one keyspace. A keyspace sets the default prefix and number of random bytes for new keys, and can have delete protection. Encrypted key storage and an IP allow list are also keyspace settings, but only support can turn them on. See Keyspaces.

Show in dashboard

Override

A different rate limit for specific identifiers in a rate limit namespace. Your code keeps sending its default limit, and we use the override’s numbers when the identifier matches. An override can match an exact identifier or a pattern with *. Use it to raise a partner’s limit or slow down an abuser without deploying. See Rate limit overrides.

Show in dashboard

Permission

A string you define and attach to keys, directly or through a role. Verification can check that a key has a permission or matches a permission query, such as documents.read AND (documents.write OR admin). See Roles and permissions.

Show in dashboard

Portal and portal session

The developer portal is a hosted page where your users see their API keys, reroll them, and check usage. It’s in beta. Your backend signs a user in by creating a portal session for their externalId, which returns a one-time URL valid for 15 minutes. The user only sees keys whose identity matches. See Developer portal.

Show in dashboard

Rate limit namespace

A name for what you’re rate limiting, such as email.send, so its counters stay separate from other limits. ratelimit.limit creates the namespace the first time you use a name, and overrides belong to a namespace. See Rate limiting with Unkey.

Show in dashboard

Recoverable key

A key created with recoverable: true, so we keep an encrypted copy you can read again with keys.getKey or apis.listKeys and decrypt: true. The keyspace needs encrypted storage, which support turns on, and the root key needs extra permissions to create and decrypt it. See Recoverable keys.

Reroll

Gives a key a new secret and keeps its settings. We create a new key, and the old key keeps working for a grace period you choose, or stops right away. Use it for scheduled rotation or after a suspected leak. See Rerolling keys.

Show in dashboard

Compute

App

A service you deploy, inside a project. The word means something specific on this site; see App under terms with more than one meaning.

Automatic domain

The unkey.app hostnames every deployment gets, so you can reach it with no DNS setup. Commit and deployment hostnames always point at that one deployment. Branch, environment, and live hostnames move to newer deployments. You can’t create, rename, or delete them. See Automatic domains.

Show in dashboard

Build and build settings

A build turns a git-connected app’s source into the container image a deployment runs. If you don’t set a Dockerfile, we detect your language and build it for you. Build settings cover the Dockerfile, root directory, build command, watch paths, and auto deploy. Each environment has its own. Apps deployed from an image have no build. See Build settings.

Show in dashboard

Custom domain

A hostname you own, such as api.acme.com, that serves one environment of an app. You add DNS records to prove you own it, and we route it and get a certificate. It always serves the environment’s current deployment, and the number you can add depends on your plan. See Custom domains.

Show in dashboard

Deployment

One built version of an app in one environment. It’s created from a git commit, an image, or an existing deployment, and keeps the image, runtime settings, environment variables, and gateway policies it started with. You can promote a production deployment or roll back to one, and stop a preview deployment or wake it again. Redeploying picks up the environment’s current settings and policies. See Deployments on Unkey.

Show in dashboard

Deployment status

Where a deployment is in its lifecycle. While it’s in progress, it moves through pending, awaiting_approval (for pull requests from forks), starting, building, deploying, network, and finalizing. It ends as ready, failed, skipped, stopped, superseded, or cancelled. See Deployments on Unkey.

Show in dashboard

Environment

Every app has two environments, production and preview, and each deployment belongs to one. Build settings, runtime settings, environment variables, regions, custom domains, and gateway policies are set per environment. See Projects, apps, and environments.

Show in dashboard

Environment variable

A key and value your app gets while it builds and while it runs. Each variable belongs to one environment, so production and preview can have different values. Values are encrypted at rest, and you can mark secrets as sensitive. See Environment variables.

Show in dashboard

Gateway

What sits in front of every deployment and receives its traffic. It handles HTTPS, routes requests by domain, and applies the deployment’s policies: key authentication, rate limiting, firewall rules, OpenAPI validation, and logging. If no instance is running in the local region, it forwards the request to the nearest region that has one. See Gateway.

Show in dashboard

Gateway policy

A rule the gateway applies to requests for an environment. Changes apply from the next deployment. The key-auth policy verifies keys from up to 5 keyspaces in the same workspace, which is where Compute and API Management connect. See Gateway policies.

Show in dashboard

Health check

An optional HTTP request we send to each instance on a schedule. An instance gets no traffic until it passes, and one that fails enough checks in a row is restarted. Set per environment. See Health checks.

Show in dashboard

Instance

One running container of a deployment in one region. The replica count sets how many instances run in each region, as a minimum and a maximum that every region shares. The dashboard labels this setting Instances, and the API calls it replicas. The minimum is at least 1, and the maximum is capped by your plan: 4 on Starter, 8 on Pro, and 16 on Business. When the maximum is above the minimum, autoscaling adds and removes instances based on CPU. See Instances and autoscaling.

Show in dashboard

Match expression

A condition that limits a gateway policy to some requests, by path, method, header, query parameter, or client IP. A request must match every expression on a policy. With none, the policy applies to every request. See Gateway policies.

Show in dashboard

Principal

Who’s calling, as identified by the gateway. When a key-auth policy verifies a key, the gateway adds an X-Unkey-Principal header with the key’s details as JSON, so your app reads one header instead of calling Unkey. See The principal header.

Project

A group of apps, usually one per codebase or product. Billing is per workspace, but the Usage page breaks Compute usage down by project, and keys verified by a key-auth policy are billed to the project. A project can have delete protection. See Projects, apps, and environments.

Show in dashboard

Promote and rollback

How you choose the live production deployment. Promote makes a ready production deployment live. Rollback moves traffic back to an earlier one and marks the app as rolled back, so new pushes build but don’t go live until you promote again. Preview deployments can’t be promoted or rolled back. See Production and preview.

Show in dashboard

Region

A place we run your instances. Compute currently runs in four AWS regions: us-west-2, us-east-1, eu-central-1, and ap-southeast-1. Each environment runs in one or more of them, and every deployment in that environment runs in all of its regions. See Regions.

Show in dashboard

Runtime settings

How big an environment’s containers are and how they run: regions, CPU, memory, instances, ephemeral disk, port, start command, and health check. Each environment has its own, and changes apply from the next deployment. See Runtime settings.

Show in dashboard

Spend budget

A monthly dollar cap on Compute usage for the whole workspace, set by an admin. We email workspace admins at 50, 75, and 100 percent, and can optionally stop your workloads at 100 percent. See Spend budget.

Show in dashboard

Standby

The 30 minutes a production deployment keeps running after it stops being live, so you can roll back to it. After that it stops, and you’d have to redeploy it to use it again. See Production and preview.