> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/scoped-tokens.md).

# Scoped tokens

Restrict a personal access token or service account token to an explicit subset of permissions.

{% hint style="info" %}
This feature is in Beta[^1] and requires enablement. [View all early access features.](https://developer.harness.io/release-notes/features.md)

{% @harness-feature-flag-access/request-feature-flag-access module="platform" pagePath="platform/use-harness-platform/automation/api/scoped-tokens" pageTitle="Scoped%20tokens" featureFlags="%5B%7B%22name%22%3A%22Scoped%20tokens%22%2C%22key%22%3A%22PL\_SCOPED\_TOKEN%22%2C%22status%22%3A%22BETA%22%2C%22description%22%3A%22Lets%20you%20restrict%20a%20personal%20access%20token%20or%20service%20account%20token%20to%20an%20explicit%2C%20declared%20subset%20of%20its%20parent%20principal's%20permissions.%22%7D%5D" %}
{% endhint %}

A personal access token (PAT) or service account token (SAT) normally inherits the full permissions of its parent user or service account. A scoped token narrows that down to an explicit subset of permissions that you declare when you create the token.

***

## What you will learn in this topic <a href="#what-you-will-learn-in-this-topic" id="what-you-will-learn-in-this-topic"></a>

By the end of this topic, you will be able to:

* [Understand how a scoped token's effective permissions are calculated](#overview).
* [Create a scoped token from the Harness UI](#create-a-scoped-token).
* [Understand the difference between persistent and ephemeral scoped tokens](#token-modes).

***

## Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* [Manage API keys](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/add-and-manage-api-keys.md): Review how standard API keys and tokens work. Scoped tokens use the same API key and token structure, with an added permission declaration.

***

## Overview <a href="#overview" id="overview"></a>

A standard token carries the full permissions of the account it is created under. If you create a personal access token, it can do anything your user account can do. This is a security risk for workloads, such as an AI agent or an automation script, that only need to perform one narrow action, such as executing a pipeline.

A scoped token lets you declare the specific permissions the token can use. Harness then evaluates every request made with that token against two things:

* **The permissions declared on the token** at creation time.
* **The actual permissions of the parent user or service account.**

{% hint style="info" %}
**EFFECTIVE PERMISSION IS AN INTERSECTION**

A scoped token's effective permission is the intersection of the two. Declaring a scope on a token can only narrow what it can do; it can never grant the token more access than the parent principal already has.
{% endhint %}

***

## Token modes <a href="#token-modes" id="token-modes"></a>

Scoped tokens support two modes:

| Mode           | How it is created                            | Expiration                                                                    |
| -------------- | -------------------------------------------- | ----------------------------------------------------------------------------- |
| **Persistent** | By you, from the Harness UI or API           | You set an expiration date when you create the token, or choose no expiration |
| **Ephemeral**  | By you or a Harness service, through the API | Expires automatically, between 5 minutes and 24 hours after creation          |

Persistent scoped tokens work like any other personal access token or service account token, with an added step to declare the permission scope. Ephemeral scoped tokens use the same token creation API, but are typically created automatically by Harness services for short-lived, narrowly scoped operations — for example, when you execute a pipeline, Harness creates an ephemeral scoped token limited to only the permissions that execution needs, and the token is discarded once the run completes.

***

## Create a scoped token <a href="#create-a-scoped-token" id="create-a-scoped-token"></a>

Use these steps to create a persistent scoped token from the Harness UI.

1. Go to your user profile in Harness, or to the service account under **Account Settings** → **Access Control** → **Service Accounts** if you are creating the token for a service account.
2. Under **My API Keys**, select an existing API key, or create a new one.
3. Select **Token**, then choose the scoped token option and add a scope rule. Select the resource type the rule applies to, for example **Connector**, **Secret**, **Pipeline**, **Service**, **Environment**, **Artifact Registry**, **Template**, or **Code Repository**.
4. Select the resource group that defines which resources of that type the rule applies to, and whether that resource group applies at the organization or project scope. You can add up to 5 scope rules on a single token.
5. Set an expiration date for the token, or select **No expiration**.
6. Select **Generate Token** and copy the token. The token is only displayed once.

{% hint style="warning" %}
**THE TOKEN'S OWN SCOPE IS ALWAYS ACCOUNT LEVEL IN THE UI**

A scoped token created from the Harness UI is always created at the account level, even when the permissions you grant it target a resource group scoped to an organization or project. The token's own scope and the scope of the permissions it carries are two separate settings.
{% endhint %}

***

## Scoped tokens from the API <a href="#scoped-tokens-from-the-api" id="scoped-tokens-from-the-api"></a>

When you create a scoped token through the Harness API, you can create the token itself at the organization or project level, not only at the account level. Go to [Get started with Harness API](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/api-quickstart.md) to review how to authenticate and make API requests, and [API permissions reference](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/api-permissions-reference.md) to review the permission identifiers you can declare on a token.

***

## Current limitations <a href="#current-limitations" id="current-limitations"></a>

* **Permission entry limits**: A token can carry at most 35 permission entries (`scopedResourcePermissions`). Each entry can declare at most 50 resource identifiers and 50 permissions. The Harness UI currently limits you to 5 scope rules per token; to declare more, use the API.
* **Ephemeral tokens are created through the API**: Ephemeral scoped tokens use the same token creation API as persistent tokens. Harness services, such as the pipeline service, use this API to create them automatically for the duration of a single operation.

***

## Next steps <a href="#next-steps" id="next-steps"></a>

* [Manage API keys](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/add-and-manage-api-keys.md): Create and edit standard API keys and tokens.
* [Agent permissions](https://developer.harness.io/harness-platform/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent/permissions.md): Configure the scoped token that Harness injects into Worker Agent pipeline steps.

{% @harness-feedback/feedback module="harness-ai" pagePath="harness-ai/use-harness-platform/automation/api/scoped-tokens" %}

[^1]: Off by default. If you want to try it and share feedback, request access and Harness will turn it on for your account. Beta features can change and may not be ready for production use.
