> 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/artifact-registry/3.0/concepts/authentication-and-identity-tokens.md).

# Authentication and identity tokens

Understand how Harness Artifacts authenticates humans and machines using PAT and service account tokens, and how RBAC applies to registry operations.

Without authentication, anyone could read from or write to a registry. This matters because internal packages contain proprietary logic, dependency caches must stay free of tampered artifacts, and compliance frameworks require knowing exactly who pushed what and when.

Harness Artifacts uses token-based authentication for every private registry operation. Throughout this documentation, an **identity token** refers to any token used as the password for a registry client, the equivalent of a personal access token (PAT) or API key in other registry tools. Understanding how tokens work, when to use each type, and how identity affects pipeline permissions prevents the most common class of access errors.

## What are the two token types?

Harness issues two kinds of tokens, each tied to a different kind of identity.

### Personal Access Tokens

A **Personal Access Token (PAT)** is tied to a human user account. When you authenticate with a PAT, Harness treats every operation as if that user performed it. The RBAC permissions of that user apply.

PATs are appropriate for interactive use: configuring your local Docker client, running CLI commands from your workstation, or testing a registry integration. They are not suitable for automated systems because they expire when the user's account is deactivated or when the token is explicitly revoked.

### Service account tokens

A **service account** is a machine identity with its own RBAC permissions, independent of any human user. A service account token authenticates that machine identity.

Service account tokens are the correct choice for CI/CD pipelines, scheduled jobs, Kubernetes workloads, and any automated process that must run reliably regardless of which humans are available. When a human leaves the team, their PAT stops working; a service account is unaffected.

## How are tokens used?

Regardless of token type, the authentication mechanism is HTTP basic auth:

| Token type            | Username                           | Password        |
| --------------------- | ---------------------------------- | --------------- |
| PAT                   | Your Harness account email address | The token value |
| Service account token | `_token`                           | The token value |

Your package manager (Docker, npm, Maven, pip, and other package managers) stores these credentials and sends them on every request to `pkg.harness.io`. The registry validates the token and applies the RBAC permissions of the associated identity before allowing or denying the operation.

## Token lifespan and scope

### Scoped tokens from Setup Client

The **Setup Client** flow in the Harness UI generates a token scoped to the current registry. You choose the expiry when you generate it: 30 days, 90 days, 180 days, or a custom duration. This token is suitable for short-lived integrations, trying out a new registry, or temporary developer access. Because it is scoped, it cannot be used to access other registries.

### Long-lived tokens from account settings

Tokens generated at the project or account level from **Account Settings > API Keys** carry a configurable expiry. A service account token for a production pipeline should have a defined rotation schedule and a longer expiry than a short-lived developer token.

{% hint style="warning" %}
**One-time visibility**

The token value is shown only once, immediately after creation. Copy and store it securely before closing the dialog. Harness does not store the raw token value and cannot retrieve it later.
{% endhint %}

## Pipeline identity and why local pipelines can fail on schedule

One of the most confusing authentication failures happens when a pipeline runs successfully on a manual trigger but fails on a scheduled trigger with a 403 error. The cause is the **pipeline identity model**.

| Trigger type                                               | Pipeline runs as                                        |
| ---------------------------------------------------------- | ------------------------------------------------------- |
| Manual (you click Run)                                     | The triggering user's RBAC permissions                  |
| Webhook, schedule, identity provider (IDP), or bot trigger | The service account or bot principal's RBAC permissions |

When you trigger a pipeline manually, it inherits your permissions. You have read access to the registry, so the pull succeeds. The scheduled run uses a service account that has not been granted that permission, so it fails.

The fix is to grant the service account the Artifact Management permissions it needs, not to expand your own permissions. This is also a security principle: production automation should use a dedicated service account with minimal permissions, not a human developer's credentials.

## RBAC and registry scope

Artifact Management permissions in Harness control what an identity can do:

| Permission    | What it allows                      |
| ------------- | ----------------------------------- |
| View          | Pull artifacts, browse the registry |
| Create / Edit | Push artifacts                      |
| Delete        | Delete artifact versions            |

Permissions apply at the scope where the registry lives. A service account with View permission at the project scope can pull from registries in that project but not from registries in other projects.

## Public registries and anonymous access

A registry set to **Public** visibility allows anonymous pulls. No token is required. Any client can pull from a public registry without authentication.

Pushing to a public registry always requires authentication, regardless of visibility setting. Harness does not allow anonymous writes.

Go to [Set registry visibility](https://developer.harness.io/artifact-registry/3.0/registries/set-registry-visibility.md) to understand when to use public or private visibility.

## Use cases

### Developer local CLI authentication

A developer configures their local Docker client once:

```bash
docker login pkg.harness.io \
  --username their@email.com \
  --password <PAT>
```

From that point, all pulls and pushes from their workstation authenticate as that developer. A scoped token from Setup Client is appropriate here.

### CI/CD pipeline using a service account

A CI pipeline that builds and pushes Docker images uses a dedicated service account. The service account token is stored as a secret in the CI system and passed to the build step as an environment variable. The pipeline never touches a human developer's credentials.

### Kubernetes imagePullSecret

Kubernetes needs credentials to pull images from a private registry. Create a long-lived service account token, then create an imagePullSecret:

```bash
kubectl create secret docker-registry harness-ar \
  --docker-server=pkg.harness.io \
  --docker-username=_token \
  --docker-password=<service-account-token>
```

Attach the secret to your pod spec. Kubernetes uses the service account identity for all image pulls.

{% @harness-feedback/feedback %}
