Scoped API Keys
Create API Keys with explicit permissions and project access for automation
A scoped API Key carries an explicit list of permissions and an explicit set of projects it may act on. Unlike a standard API Key, which inherits the full access of the user who created it, a scoped key grants only what you select when you create it. That makes it a better fit for CI/CD pipelines, Terraform, GitOps, and any other long-lived automation.
Scoped keys are additive. Existing API Keys continue to work unchanged, and both kinds of key can be created and used side by side.
How scoped keys differ
Key prefix
bps_
bp_
Permissions
Explicitly selected at creation
Inherits the creating user's role
Project access
Explicitly selected at creation
The project the key was created in
Requires the account header
Yes, on every request
No
Best for
CI/CD, Terraform, GitOps, long-lived automation
Interactive CLI use and quick scripts
Scopes
Every scoped key is created with one of two scopes.
Project scope grants access to a specific list of projects, chosen when the key is created. All selected projects must belong to the same organization.
Organization scope grants access to every project in the organization, including projects created after the key was issued. Only organization admins can create organization-scoped keys, and only organization-scoped keys can hold organization-level permissions such as ReadOrganizations and WriteOrganizations.
Which scopes you can choose depends on where you create the key. Project Settings creates project-scoped keys. Organization Settings creates either scope.
Creating a key from Project Settings
Use this when the key only needs access to projects you are a member of. Keys created here are always project-scoped.
Open the Project Settings page from the top-right hamburger menu.
Navigate to the API Keys section, click the Create API Key dropdown, and choose Create API Key. The second option, Create API Key (classic), creates a standard API Key instead.
In the dialog:
Optionally add a Description (up to 256 characters) so the key is identifiable later.
Choose an Expiration: no expiration, or 30, 60, 90, 180, or 365 days.
Select the Projects the key may access. The project you are currently in is always included and cannot be removed. Add any other project you are a member of, as long as it belongs to the same organization.
Click Add permissions and select each resource the key needs. For every resource you add, choose Read-only or Read and write.
Click Create.
Creating a key from Organization Settings
Use this when the key needs access to every project in the organization, or to projects you are not a member of. This page is only available to organization admins.
Open the Organization Settings page and navigate to the API Keys section, then click Create API Key. There is no classic option here, so every key created from this page is scoped.
The dialog is the same as above with one addition: a Scope selector, which defaults to Organization.
Leave Scope set to Organization for a key that reaches every project in the organization, now and in the future. The Projects field disappears, and the Organization resource becomes available in the permission list.
Set Scope to Project to pick specific projects instead. Any project in the organization can be selected, and unlike Project Settings, no project is pre-selected for you.
Tip
📘 Choose the minimal permissions necessary. A key that only reads agent status needs nothing beyond read access to Agents.
After the key is created
Whichever page you used, a window will show you your new API Key along with a ready-to-run bindplane profile set command. This will be the only time this key is available to you. If you do not copy the key now you will have to delete the key and generate another one.
A key must be created with at least one permission, and you cannot grant a key more than you hold yourself. Permissions you lack are rejected at creation.
Using a scoped API Key
Every request made with a scoped key must identify the project it is acting on. Scoped keys can reach more than one project, so unlike a standard key they cannot infer one.
With the CLI, set the project on the profile using --project. The dialog that displays a new key includes this command with the values already filled in:
You can also append --project to any individual command, which overrides whatever the profile has set. This is the simplest way to drive several projects with one key:
To keep separate settings per project instead, create a named profile for each and select one with --profile:
With the REST API, send the project ID in the X-Bindplane-Account-ID header alongside the key:
Caution
📘 A request made with a scoped key and no X-Bindplane-Account-ID header is rejected with 401 Unauthorized. This applies to organization-scoped keys too. An organization-scoped key must still name a project in the organization it is acting on.
If the key's scope does not cover the project named in the header, the request is rejected with 401 Unauthorized. If the key's scope covers the project but the key lacks the permission the endpoint requires, the request is rejected with 403 Forbidden and an error naming the missing permission.
Expiration
Keys can be created with no expiration or with an expiration up to 365 days out. The API Keys table shows a status for each key:
Active
No expiration, or more than 30 days remaining
Expiring soon
30 days or fewer remaining
Expired
Past its expiration date, so authentication fails
Expired keys are not removed automatically. Rotate a key by creating its replacement, updating your automation, and then deleting the old key.
Viewing and deleting keys
Each user can have up to 25 API Keys per project. This limit counts scoped and standard keys together. When a user reaches the limit, the Create API Key button is disabled and a warning appears above the table.
Organization admins can use the organization view to see every API Key in the organization, across all projects and all users, scoped and standard alike. For each key the list shows its description, the projects it can reach (All projects for an organization-scoped key), when it was created, when it was last used, and its expiration status. An organization admin can delete any key in the list.
Within a single project, the API Keys table shows the keys you can manage. A key that also grants access to projects you are not an admin of is listed but cannot be deleted from the project page. An organization admin must remove it.
Deletion takes effect immediately. Any automation still presenting the key begins receiving 401 Unauthorized.
Permissions
In the create dialog, permissions are grouped by resource. Selecting Read-only grants the read permission. Selecting Read and write grants both the read and write permission for that resource.
Agents
ReadAgents
WriteAgents
Project or Organization
Agent Types
ReadAgentTypes
WriteAgentTypes
Project or Organization
Agent Versions
ReadAgentVersions
WriteAgentVersions
Project or Organization
API Keys
ReadAPIKeys
WriteAPIKeys
Project or Organization
Available Components
ReadAvailableComponents
None
Project or Organization
Bindplane Telemetry
ReadBindplaneTelemetry
None
Project or Organization
Configurations
ReadConfigurations
WriteConfigurations
Project or Organization
Offline Agent Versions
None
WriteOfflineAgentVersions
Project or Organization
Organization
ReadOrganizations
WriteOrganizations
Organization only
Projects
ReadProjects
WriteProjects
Project or Organization
Resources
ReadResources
WriteResources
Project or Organization
Rollouts
ReadRollouts
WriteRollouts
Project or Organization
Secrets
ReadSecrets
WriteSecrets
Project or Organization
Users
ReadUsers
WriteUsers
Project or Organization
Note
📘 The Organization resource is only offered when the key's scope is Organization. A project-scoped key cannot hold organization-level permissions.
Read permissions cover the GET endpoints for that resource, and write permissions cover the endpoints that create, modify, or delete it. See the OpenAPI reference for the endpoints themselves. If a key is missing the permission an endpoint requires, the response is 403 Forbidden and names the missing permission, so you know what the replacement key needs.
Some operations cannot be performed with an API Key at all and are reachable only by a logged-in user in the UI. These include deleting a project, creating or deleting an organization, all SSO configuration, creating and deleting secret keys, and syncing agent versions. As a result, WriteAgentTypes, WriteAgentVersions, WriteOfflineAgentVersions, and WriteSecrets can be granted to a key but currently unlock nothing.
Caution
📘 Creating a project requires WriteOrganizations, which in turn requires an organization-scoped key. A project-scoped key cannot create projects, even with the Projects write permission.
Last updated
Was this helpful?