> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/cli-and-api/scoped-api-keys.md).
# Scoped API Keys
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
| | Scoped key | Standard key |
| --------------------------- | ----------------------------------------------- | ------------------------------------- |
| 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:
1. Optionally add a **Description** (up to 256 characters) so the key is identifiable later.
2. Choose an **Expiration**: no expiration, or 30, 60, 90, 180, or 365 days.
3. 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.
4. Click **Add permissions** and select each resource the key needs. For every resource you add, choose **Read-only** or **Read and write**.
5. 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.
{% hint style="success" %}
**Tip**
📘 Choose the minimal permissions necessary. A key that only reads collector status needs nothing beyond read access to Collectors.
{% endhint %}
### 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:
```shell
bindplane profile set default \
--api-key bps_01J8ZQ3K7YV2N4XW5R6T8B9CDE.4689832f-1725-4eeb-8f9d-3e78cb0152ec \
--remote-url https://app.bindplane.com \
--project 01GWSWFR21BTG5YD0HWZY12W6V
```
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:
```shell
bindplane get configurations --project 01GWSWFR21BTG5YD0HWZY12W6V
bindplane get configurations --project 01HXYZ8M4KQ7R2VN6T5B9WCDEF
```
To keep separate settings per project instead, create a named profile for each and select one with `--profile`:
```shell
bindplane get configurations --profile production
```
With the REST API, send the project ID in the `X-Bindplane-Account-ID` header alongside the key:
{% code overflow="wrap" %}
```shell
curl -H 'X-Bindplane-Api-Key: bps_01J8ZQ3K7YV2N4XW5R6T8B9CDE.4689832f-1725-4eeb-8f9d-3e78cb0155ec' \
-H 'X-Bindplane-Account-ID: 01GWSWFR21BTG5YD0HWZY12W6V' \
https://app.bindplane.com/v1/configurations
```
{% endcode %}
{% hint style="warning" %}
**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.
{% endhint %}
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:
| Status | Meaning |
| ------------- | ------------------------------------------------- |
| 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.
| Resource | Read permission | Write permission | Scope required |
| -------------------------- | ------------------------- | --------------------------- | ----------------------- |
| Collectors | `ReadAgents` | `WriteAgents` | Project or Organization |
| Collector Types | `ReadAgentTypes` | `WriteAgentTypes` | Project or Organization |
| Collector 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 Collector 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 |
{% hint style="info" %}
**Note**
📘 The Organization resource is only offered when the key's scope is Organization. A project-scoped key cannot hold organization-level permissions.
{% endhint %}
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](https://app.bindplane.com/swagger/index.html) 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 collector versions. As a result, `WriteAgentTypes`, `WriteAgentVersions`, `WriteOfflineAgentVersions`, and `WriteSecrets` can be granted to a key but currently unlock nothing.
{% hint style="warning" %}
**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.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.bindplane.com/cli-and-api/scoped-api-keys.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.