- Classic API keys carry a fixed set of permissions for a single scope. What a classic key can do is determined by the kind of key it is, and cannot be changed.
- Fine-grained API keys carry only the permissions you select when you create the key. Each key is bound to a scope and its descendants, expires on a date you choose, and cannot be edited after creation.
Key types
See API Key Permissions for the full set of permissions a project API key carries.
How fine-grained keys work
A fine-grained key is defined by three things you choose when you create it:- A scope it is bound to. Either an organization or a workspace. This scope is the key’s root, and it determines everything the key can reach.
- A set of permissions. You select these individually from the permissions available at that scope. Nothing is selected by default.
- An expiration date. Required, and capped at 365 days.
Authorization header. The endpoints that manage projects and alerts accept fine-grained keys only, so a project API key is rejected there.
What a key can reach
A key reaches its root scope and every scope beneath it, and nothing outside it. For example, a key rooted at a workspace can act on that workspace and on every project inside it, but not on the parent organization or on anything in a sibling workspace. A key rooted at an organization reaches every workspace and project in that organization. Coverage is evaluated on every request, not fixed at creation. A project created after the key was issued is covered automatically, with no change to the key. Archived scopes drop out of coverage. The root also bounds which permissions the key can be given: the create-key dialog only offers permissions that apply at the root scope or below, so a workspace-rooted key is never offered organization-level permissions.Because a key covers all current and future descendants of its root, prefer the narrowest root that still works. A key that only manages one team’s projects belongs on that team’s workspace, not on the organization.
Creating a fine-grained key
You need permission to create keys on the scope you are creating them for. Org Admins can create organization-rooted keys, and Workspace Admins can create workspace-rooted keys. See Permission Reference.1
Open the API Keys settings for the scope
For a workspace-rooted key, go to Settings > Workspace > API Keys. For an organization-rooted key, go to Settings > Organization > API Keys.
2
Click Create API Key
Give the key a name that identifies the workload using it, for example
ci-project-provisioning. The description is optional. Use it to explain the key’s purpose to whoever inherits it.3
Set an expiration
Choose one of the presets or a custom date. The default is 90 days and the maximum is 365 days. Plan to create the replacement key before this date.
4
Select permissions
Check only the permissions the workload needs. You cannot add permissions later.
5
Copy the key
Click Create Key, then copy the full key value from the dialog and store it in your secret manager. This is the only time the value is shown. HoneyHive stores only a hash of it, so it cannot be recovered or displayed again.
hh_fgcp_<key id>_******. The visible portion is the key’s id, not part of its secret, so you can match a key in the list to a key in your logs without exposing anything sensitive.
Revoking a key
Open the API Keys page for the scope the key is rooted on and revoke it from the key’s row. Revocation takes effect immediately. The next request made with that key fails. Revoked and expired keys stay in the list, marked as revoked or expired, alongside who created them, who revoked them, and when. This history lets you audit key usage, including after someone leaves the team, so the list is not meant to be pruned. To rotate a key, create the replacement first, move your workload over to it, then revoke the old key.Restricting what keys can carry
Organizations can narrow the permissions anyone is allowed to put on a fine-grained key. Go to Settings > Organization > API Key Policy and select the permissions that keys in this organization may carry. Anything you leave out is unavailable in every create-key dialog, at every scope in the organization. This is useful when workspace admins can mint their own keys but your security team wants to bound what those keys can ever do. Changing the policy requires permission to manage role definitions, which workspace admins do not have, so the limit holds even though they are the ones creating keys. Two things to know:- By default no restriction is applied, and the full set of available permissions is offered.
- The policy applies when a key is created. Narrowing it does not change or revoke keys that already exist. To withdraw a permission from an existing key, revoke that key directly.
Security guidance
- Grant key creation deliberately. Someone who can create keys on a scope can issue a key that acts on every scope beneath it, including projects they cannot access themselves. Only grant this to people you would trust with that access directly.
- One key per workload. Separate keys for separate systems keep the blast radius small and make it obvious which key to revoke.
- Store keys in a secret manager. Never commit a key or paste it into application code.
- Rotate on a schedule. Expiry dates give you a natural rotation cadence. Replace keys before they lapse rather than after a failure.
Related
Roles and permissions
How permissions and roles work across scopes
Organization hierarchy
How organizations, workspaces, and projects nest
Managing projects
Create and organize projects
Alerts
Monitor cost, latency, errors, and evaluator scores