# Repository Tokens: Create One and Authenticate

> Create a CloudRepo repository token (access token) and use it for Maven, Gradle, npm, pip, twine and docker login. The username is your email address.

A *repository token* is the credential your build tools send to CloudRepo in place of a password. Other tools call it an access token or an API token.

## Pick the Right Credential

| Credential                               | Use it for                           | Who makes it, and where                                                                                                                    | What it reaches                                                                                          |
| ---------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Repository token, `crp_v1_`              | You: your laptop and your own builds | Any user, for themselves, under **Repository Tokens** ([steps](#create-a-token-in-the-admin-portal))                                       | The repositories you tick, **Download packages** or **Download and publish packages**                    |
| Organization token (service key), `crk_` | CI                                   | The organization owner or an Admin ([how](#service-keys-for-your-pipelines))                                                               | The repositories picked when it is made, to download, or to download and publish, until the date it ends |
| Subscriber access key                    | Your customers                       | A user with **Manage software distribution**, under **Software Distribution** ([how](/docs/manage/software-distribution.html#access-keys)) | Read only: the repositories its subscriber’s groups grant                                                |
| `npm login` token, `crn_v1_`             | npm only                             | You, by running `npm login` against a Hosted npm repository ([how](/docs/formats/npm.html#connect-npm))                                    | That one repository, read only unless you choose **Read-write**                                          |

## Create a Token in the Admin Portal

1. Sign in to the [admin portal](https://admin.cloudrepo.io) as the user whose builds will use the token, and click **Repository Tokens** in the sidebar.

2. Click **Create token**, or **Create your first token** if you have none. If the form says **No repositories available**, [create a repository](/docs/manage/repositories.html#creating-a-repository) first.

   ![The Create repository token form: an empty Name field, Access set to Download packages, and five repositories to tick.](/docs/_astro/shots/repository-tokens/2-create-form.55a89b8cfedc4219.png)

3. Give the token a **Name** that says where it is used, such as `laptop-maven`. The name is a label, never the username.

4. Under **Access**, choose **Download packages** or **Download and publish packages**. Publishing also lets it delete npm packages and Docker images. Whether it can replace a published version is the repository’s setting: Overwrite Protection for Maven releases (SNAPSHOT versions can always be replaced), npm and Python (on by default), Immutable Tags for Docker. A user with read-only access can create **Download packages** tokens only. Under **Repositories**, tick each repository the token may reach. You cannot change them later.

   A token that ticks a group reads the group’s current members through the group’s URL, read only. A member’s own URL needs that member ticked too.

5. Under **Expires**, keep the default of 90 days, click **180 days** or **365 days**, pick a date up to 31 December 9999, or click **Never expires**. A date ends at its start (00:00 UTC), so pick the day after the last day you need.

6. Click **Create token**. If you have not confirmed your identity in the last 15 minutes, the **Confirm Your Identity** dialog asks for your password first: enter it and click **Confirm**. A confirmation you obtained with your password stops working once you enroll a second factor; confirm again with that factor. Then click **Copy**, and keep the token where your build reads it, such as a CI secret. CloudRepo shows it only once.

   ![Token created, with the token value shown once and a Copy button.](/docs/_astro/shots/repository-tokens/7b-token-created.76030a5aadac74e2.png)

## Use the Token in Your Client

Every client sends the token in place of a password. For a token you made, the username is your email address, the address of the account that created the token, in any case. A username of `__token__`, `token` or anything else answers `401 Unauthorized`. An organization token is the exception: it accepts any username, and the token is the secret. The portal fills in the word `token` ([how](#service-keys-for-your-pipelines)).

| Client     | Username                         | Password                               | Set it up                                                                  |
| ---------- | -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------- |
| Maven      | Your email address               | The token                              | [Publish](/docs/publish/maven.html), [install](/docs/consume/maven.html)   |
| Gradle     | Your email address               | The token                              | [Publish](/docs/publish/gradle.html), [install](/docs/consume/gradle.html) |
| npm        | None                             | The token, as `_authToken` in `.npmrc` | [Publish](/docs/publish/npm.html), [install](/docs/consume/npm.html)       |
| pip, twine | Your email address               | The token                              | [Publish](/docs/publish/python.html), [install](/docs/consume/python.html) |
| Poetry, uv | Your email address               | The token                              | [Poetry](/docs/formats/poetry.html), [uv](/docs/formats/uv.html)           |
| Docker     | Your email address (not checked) | The token                              | [Push](/docs/publish/docker.html), [pull](/docs/consume/docker.html)       |
| curl       | Your email address               | The token                              | [Raw files over HTTP](/docs/formats/raw.html)                              |

To replace a password in a build, keep its username and put the token where the password was.

## Replace a Token Without Breaking Builds

Rotate a token to get a new value with the same name, repositories, scope and expiry. The old value keeps working while you swap in the new one.

1. On **Repository Tokens**, click **Rotate** on the token’s row.
2. Under **Overlap window**, choose how long the old value keeps working: 24 hours by default, 0 to stop it now, and at most 168 hours (7 days), never past the token’s expiry.
3. Click **Rotate token**, confirm your identity if the portal asks, and copy the **New token value**.
4. Put the new value in your CI secret, or wherever the build reads it.
5. Run one build. When it passes, the new token’s **Last used** shows a date instead of **Never used**.
6. Click **Revoke** on the old token’s row, then **Yes, revoke this token**. If you skip this step, the old value stops working when the overlap ends.

A revoked token stops working at once: the next request that sends it answers `401 Unauthorized`. A token also stops working on the date its **Expires** column shows. A rotation keeps that date, so to move it, create a new token, then do steps 4 to 6 with it.

If your organization uses SSO, a token a member creates after an SSO sign-in has a renewal date. When it comes before the expiry, **Expires** shows **Renew by** and that date. The token stops working on it until that member renews it, signed in through your identity provider (`POST /api/repository-tokens/<token-id>/renew`). Renewing keeps the value, so builds keep working.

## See Which Builds Still Sign In With a Password

On **Repository Tokens**, the organization owner and users with **Manage users** see **Builds that sign in with a password**: each member who can sign a build in with a password, with the **Last password build**, the **Client** and the **Repositories**. **From** shows the network the last build came from, to help you find the CI host, and **Token** shows whether the member already has a repository token. Above the list, a line says how many of these members signed a build in with a password in the last 30 days.

- On your own row, click **Switch**. The token form opens with that build’s repositories ticked.
- On another member’s row, click **Copy switch link** and send it. They sign in, confirm it is them, and get a token for their builds.

## Service Keys for Your Pipelines

A service key is now called an organization token. It is the credential for CI and build servers. It belongs to your organization, not to a person, so removing members never breaks it.

The organization owner or an Admin makes organization tokens in the admin portal, on **Repository Tokens**. Each one lasts up to a year. In your build, use the word `token` as the username. The same page lists them all under **Organization tokens**, where you revoke one too. To compare an organization token with your own tokens, see [Which credential do I use?](/docs/authenticate/which-credential.html)

1. In the [admin portal](https://admin.cloudrepo.io), click **Repository Tokens** in the sidebar. Click **Create token** at the top of the page, or **Create an organization token** under **Organization tokens**, which opens the form with **Organization** already chosen.

2. Under **Owner**, choose **Organization**. The form tells you how your build signs in: “Your build signs in with the word `token` as its username and this token as its password. For npm, the token goes in .npmrc as \_authToken instead.”

3. Give the token a **Name**, such as `ci-build`. Under **Access**, choose **Download packages** or **Download and publish packages**. Under **Repositories**, tick each repository it may reach.

4. Under **Expires**, keep the default of 90 days, click **180 days** or **365 days**, or pick a date. An organization token lasts at most 1 year. The form has no **Never expires** for it.

5. Click **Create token**, then enter a code from your authenticator app.

6. Click **Copy**, and store the token in your CI’s secret store. CloudRepo shows it only once. Under **Set up your build**, the portal shows the settings for your repositories’ tools, with `token` already filled in as the username.

Making an organization token needs two-factor authentication on your own account. Without it, the form says: “Set up two-factor authentication on your own account first: creating an organization token needs a code from your authenticator app.” See [Set up MFA for your own account](/docs/manage/mfa.html#set-up-mfa-for-your-own-account).

Your organization tokens are listed on **Repository Tokens**, under **Organization tokens**. Each row shows the token’s **Name**, **Access** and **Repositories**, when it **Ends**, when it was **Last used**, and who it was **Created by**. Service keys you made with the script are listed there too. Revoked and expired tokens move to **Ended organization tokens**, as a record.

Before a token ends, make the next one and put it in your CI. To stop one sooner, click **Revoke** on its row, then **Revoke token**. Anything that uses it is refused.

## When a Client Answers 401, 403 or 404

`401 Unauthorized` means the credential was refused. `403 Forbidden` means it may not do what was asked. A Proxy repository answers `404 Not Found` instead of `403`, except for an `npm login` token, which it refuses with `403`.

Docker asks for access before every pull or push. If the token doesn’t reach the repository, or the repository doesn’t exist, the answer is `403` with `denied: requested scope not authorized for this token`.

To npm, a token that is mistyped, expired, revoked or from another organization answers `404 Not Found`, not `401`. If npm reports `404` for a package that exists, check the token first.

Check these in order:

- *The username.* For a token you made, your email address, not `__token__`, the token’s name or your organization’s name. An organization token accepts any username, so the username is not the cause.

- *The token.* Paste it whole, from `crp_v1_`, or `crk_v1_` for an organization token. On **Repository Tokens**, check that it has not expired or been revoked.

- *The repository.* A token reaches only the repositories ticked when it was created.

  Through a group’s URL, ticking the group is enough; a member’s own URL needs the member ticked.

- *Publishing.* A **Download packages** token cannot publish: use **Download and publish packages**.

- *An `npm login` token.* It works only on the Hosted npm repository it was created for. A Proxy npm repository or a group refuses it with `403`: use a token from **Repository Tokens** there.

- *A second factor.* If you’ve set up a second factor, your portal password no longer works for builds. Use a repository token instead.

- *Password builds turned off.* When your organization’s owner turns off password builds, a build that sends a member’s password instead of a token answers `401 Unauthorized` with: “This organization accepts repository tokens only, not passwords. Create a token and use it in place of your password.” The answer links to your **Repository Tokens** page and to [Use the Token in Your Client](#use-the-token-in-your-client). Keep the build’s username, your email address, and put a token where the build kept the password.

- *If your organization builds with repository tokens only,* a password never works in a build tool.

---

The page: https://www.cloudrepo.io/docs/authenticate/repository-tokens.html
