> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/developer/authentication/scoped-api-keys.md).

# Scoped API Keys

{% hint style="warning" %}
This feature is only available to Enterprise customers.
{% endhint %}

Scoped API keys let you issue an API key that has specific permissions.

For example, you can issue an API key that allows you to manage images in a Project, but does not allow you to manage models.

To create a scoped API key, go to your [Settings - API keys](https://app.roboflow.com/settings/api):

<figure><img src="/files/pcwkm2uQkUefKdpsMZYr" alt=""><figcaption></figcaption></figure>

Next, click "Generate New Key":

<figure><img src="/files/P9lTiRc2twAHFUfreRWn" alt=""><figcaption></figcaption></figure>

This will add a new key to your Workspace.

To define the scope for the API key, click the edit icon in the table row of the API key you want to update.

A window will appear where you can set a name for and define the scope for your API key:

<figure><img src="/files/hwiJXzDeua6ojrAFaIKy" alt=""><figcaption></figcaption></figure>

You can customise API key scopes at any time.

If you do not have access to this feature and are on an enterprise plan, contact your Roboflow account representative.

## Available scopes

Each scope string is a section prefix plus a leaf action, joined by a colon (for example `model:infer`). When you create or update a key programmatically, pass the leaf scope strings in the `scopes` array.

{% hint style="info" %}
**Section shorthand.** Passing a bare section name (e.g. `model`) grants **every** scope in that section (`model:infer`, `model:deploy`, `model:manage`). Use a section name to grant the whole group, or individual leaf scopes for finer control.

Section shorthand is **accepted as input** but expanded to explicit **leaf** scopes **at write time** - a key created with `scopes: ["model"]` is stored and reads back as `["model:infer", "model:deploy", "model:manage"]`, not `["model"]`. The shorthand token itself never lands in storage, so a key granted `model` does not auto-gain any ability added to that section later.
{% endhint %}

<table><thead><tr><th width="160">Section</th><th width="230">Scope</th><th>Grants</th></tr></thead><tbody><tr><td><code>workspace</code></td><td><code>workspace:read</code></td><td>Read details about a workspace</td></tr><tr><td><code>project</code></td><td><code>project:create</code></td><td>Create a project</td></tr><tr><td><code>project:read</code></td><td>List and read details of projects</td><td></td></tr><tr><td><code>project:update</code></td><td>Update project details and active learning configuration</td><td></td></tr><tr><td><code>workflow</code></td><td><code>workflow:create</code></td><td>Create a workflow</td></tr><tr><td><code>workflow:read</code></td><td>List and read details of workflows (and run them)</td><td></td></tr><tr><td><code>workflow:update</code></td><td>Update details of workflows</td><td></td></tr><tr><td><code>folder</code></td><td><code>folder:create</code></td><td>Create a folder</td></tr><tr><td><code>folder:read</code></td><td>List and read details of folders</td><td></td></tr><tr><td><code>folder:update</code></td><td>Update folder details</td><td></td></tr><tr><td><code>folder:delete</code></td><td>Delete a folder</td><td></td></tr><tr><td><code>image</code></td><td><code>image:create</code></td><td>Upload images to a project</td></tr><tr><td><code>image:read</code></td><td>List and read details of images</td><td></td></tr><tr><td><code>image:tag</code></td><td>Add tags and write user metadata to images</td><td></td></tr><tr><td><code>image:annotate</code></td><td>Add annotations to an image</td><td></td></tr><tr><td><code>model</code></td><td><code>model:infer</code></td><td>Infer on a model in the workspace</td></tr><tr><td><code>model:deploy</code></td><td>Deploy a model to the workspace</td><td></td></tr><tr><td><code>model:manage</code></td><td>Manage models saved in the model registry</td><td></td></tr><tr><td><code>model-eval</code></td><td><code>model-eval:read</code></td><td>List and read details of model evaluations</td></tr><tr><td><code>device</code></td><td><code>device:read</code></td><td>Read details about a device in a workspace</td></tr><tr><td><code>device:update</code></td><td>Update a device in a workspace</td><td></td></tr><tr><td><code>vision-events</code></td><td><code>vision-events:read</code></td><td>Query and read vision events</td></tr><tr><td><code>vision-events:write</code></td><td>Create and upload vision events</td><td></td></tr><tr><td><code>vision-events:manage</code></td><td>Create, update, and archive use cases</td><td></td></tr><tr><td><code>workspace-stats</code></td><td><code>workspace-stats:read</code></td><td>Read workspace usage and annotation statistics</td></tr><tr><td><code>batch</code></td><td><code>batch:read</code></td><td>List and view details about uploaded image batches</td></tr><tr><td><code>version</code></td><td><code>version:create</code></td><td>Create a dataset version</td></tr><tr><td><code>version:read</code></td><td>List and read details of dataset versions</td><td></td></tr><tr><td><code>version:update</code></td><td>Update dataset versions</td><td></td></tr><tr><td><code>training-job</code></td><td><code>training-job:create</code></td><td>Create model training jobs in a workspace</td></tr><tr><td><code>annotation-job</code></td><td><code>annotation-job:create</code></td><td>Create an annotation job</td></tr><tr><td><code>annotation-job:read</code></td><td>List and read details of annotation jobs</td><td></td></tr><tr><td><code>video-inference-job</code></td><td><code>video-inference-job:create</code></td><td>Create a video inference job</td></tr><tr><td><code>video-inference-job:read</code></td><td>Read details of a video inference job</td><td></td></tr><tr><td><code>integration</code></td><td><code>integration:create</code></td><td>Create a third-party integration</td></tr><tr><td><code>integration:delete</code></td><td>Delete a third-party integration</td><td></td></tr><tr><td><code>credentials</code></td><td><code>credentials:create</code></td><td>Create a credential</td></tr><tr><td><code>credentials:read</code></td><td>List and read credentials</td><td></td></tr><tr><td><code>credentials:update</code></td><td>Update a credential</td><td></td></tr><tr><td><code>credentials:delete</code></td><td>Delete a credential</td><td></td></tr><tr><td><code>data-staging</code></td><td><code>data-staging:read</code></td><td>Access the metadata of staged batches</td></tr><tr><td><code>data-staging:write</code></td><td>Append content to data staging</td><td></td></tr><tr><td><code>data-staging:delete</code></td><td>Delete staged batches, shards, and files</td><td></td></tr><tr><td><code>batch-processing</code></td><td><code>batch-processing:read</code></td><td>Access the metadata of the Roboflow Batch Processing service</td></tr><tr><td><code>batch-processing:trigger</code></td><td>Trigger jobs using Roboflow Batch Processing</td><td></td></tr><tr><td><code>api-key</code></td><td><code>api-key:read</code></td><td>List API keys and read their metadata (never their secret values)</td></tr><tr><td><code>api-key:create</code></td><td>Create new API keys</td><td></td></tr><tr><td><code>api-key:update</code></td><td>Update an API key's name, scopes, metadata, protection, and enabled state</td><td></td></tr><tr><td><code>api-key:revoke</code></td><td>Permanently revoke API keys (disabling/re-enabling uses <code>api-key:update</code>)</td><td></td></tr></tbody></table>

## Role presets

Instead of listing individual scopes, you can grant the scopes of an RBAC **role** by passing a `role:<name>` token in the `scopes` array. It expands to that role's API scopes when the key is created or updated:

* **Built-in roles:** `role:labeler`, `role:reviewer`, `role:owner`. `role:owner` grants **full access** (an unscoped key).
* **Custom roles:** `role:<display name>` (or the custom role's id) for any custom role defined in your workspace.
* **Composable:** mix presets with explicit scopes, e.g. `["role:reviewer", "model:infer"]`. Overlaps are de-duplicated.

Presets are **expanded at create/update time** and stored as concrete leaf scopes, the same way [section shorthand](#available-scopes) is normalized on write. An unknown role name returns `400`. Like any scopes, a preset is **subset-enforced** - you can only grant a role whose abilities are within the credential running the request, so a restricted key can't use `role:owner` to escalate - and using presets requires the **Advanced API Keys** feature.

## Manage keys programmatically

You can also create scoped keys (and list, rename, protect, disable, and revoke keys) without the dashboard, using the [REST API](/developer/rest-api/manage-api-keys.md), the [`roboflow api-key` CLI](/developer/command-line-interface/manage-api-keys.md), or the [MCP server](/developer/mcp-server.md). A key created this way can only be granted scopes the calling credential already holds.