docs(tokens): several project tokens per project, shown once

api-reference/README.md

@@ -31,10 +31,10 @@ The Argos API authenticates requests with a **bearer token**. Add an `Authorizat
 Authorization: Bearer <your-token>
 ```
 
-In most cases this is a **project token**, which you can find in your project settings on [argos-ci.com](https://argos-ci.com). A project token grants access to a single project, so it's safe to use in your CI environment.
+In most cases this is a **project token**. Create one in your project's **Settings → Authentication** on [argos-ci.com](https://app.argos-ci.com), or in **Team Settings → Tokens** for a token linked to several projects. Argos shows it only once: copy it when you create it. A project token only reaches the projects it is linked to, and only the endpoints its permissions cover, so it's safe to use in your CI environment. See [Project tokens](https://argos-ci.com/docs/learn/account-and-access/project-tokens) for permissions, expiration, and rotation.
 
 {% hint style="warning" %}
-Your token carries the ability to create and update builds in your project. Keep it secret: store it as a CI secret or environment variable, and never commit it to version control or expose it in client-side code.
+Your token can create and update builds in your project, depending on its permissions. Keep it secret: store it as a CI secret or environment variable, and never commit it to version control or expose it in client-side code.
 {% endhint %}
 
 Some endpoints act on behalf of a user rather than a project — for example, submitting a review, posting a comment, or resolving a thread. These require a **personal access token**, which is attributed to your Argos user and checked against your project permissions. You can create one in your personal settings on [argos-ci.com](https://argos-ci.com).

docs/SUMMARY.md

@@ -87,6 +87,7 @@
   * [Account management](learn/account-and-access/account-management.md)
   * [Analytics](learn/account-and-access/analytics.md)
   * [Team members & roles](learn/account-and-access/team-members-and-roles.md)
+  * [Project tokens](learn/account-and-access/project-tokens.md)
   * [Passkeys](learn/account-and-access/passkeys.md)
   * [GitHub single sign-on](learn/account-and-access/github-single-sign-on.md)
   * [SAML single sign-on](learn/account-and-access/saml-single-sign-on.md)

docs/agents/mcp-server.md

@@ -25,6 +25,7 @@ It integrates with popular AI assistants like Claude, enabling them to:
 - Read and post comments on builds and tests
 - Investigate flaky tests and ignore the changes behind them
 - Read and update project settings, contributors, deployments, and automation rules
+- Create, list, and revoke [project tokens](../learn/account-and-access/project-tokens.md)
 - Manage a team's members, invites, and email domains
 - Retrieve project metadata, account analytics, plan, and usage
 - Upload standalone images and videos and get shareable links for them
@@ -35,9 +36,9 @@ The server is remote and uses the **streamable HTTP** transport — there is no
 
 Tools are generated directly from the [Argos REST API](https://argos-ci.com/docs/api-reference): every API operation that a user can call is exposed as an MCP tool with the same name, parameters, and permissions. When the API gains an endpoint, the MCP server gains the matching tool — with no client update on your side.
 
-Agents can list builds and inspect their screenshot diffs, approve or reject changes, request reviewers, read and post comments, diagnose flaky tests and ignore their recurring changes, configure projects and their contributors, manage automation rules, administer a team's members and invites, upload and share [standalone media](../learn/media/) and read the comments left on it, and retrieve account analytics and usage. Ask your client to list the server's tools, or see the [API reference](https://argos-ci.com/docs/api-reference) for the underlying operations.
+Agents can list builds and inspect their screenshot diffs, approve or reject changes, request reviewers, read and post comments, diagnose flaky tests and ignore their recurring changes, configure projects and their contributors, manage automation rules and project tokens, administer a team's members and invites, upload and share [standalone media](../learn/media/) and read the comments left on it, and retrieve account analytics and usage. Ask your client to list the server's tools, or see the [API reference](https://argos-ci.com/docs/api-reference) for the underlying operations.
 
-What an agent may actually do is decided by the scopes you grant it, not by the tool list: `projects:read` for inspecting projects, builds and tests, `reviews:write` for reviews, review requests and ignoring changes, `comments:write` for comments and notification subscriptions, `projects:write` for project configuration and automation rules, `media:read` and `media:write` for uploading and managing shared media, and `account:admin` for team administration.
+What an agent may actually do is decided by the scopes you grant it, not by the tool list: `projects:read` for inspecting projects, builds and tests, `reviews:write` for reviews, review requests and ignoring changes, `comments:write` for comments and notification subscriptions, `projects:write` for project configuration, automation rules and project tokens, `media:read` and `media:write` for uploading and managing shared media, and `account:admin` for team administration.
 
 ## Authentication
 

docs/learn/account-and-access/README.md

@@ -9,6 +9,7 @@ Manage your Argos account, how you sign in, and who on your team can access what
 * [Account management](account-management.md) – Sign up, create projects and teams, and manage login methods and emails
 * [Analytics](analytics.md) – Track builds, screenshots, change rate, and approval rate across your projects
 * [Team members & roles](team-members-and-roles.md) – Invite members and control their permissions with roles
+* [Project tokens](project-tokens.md) – Create the tokens CI uploads with, scope their permissions, and rotate them without downtime
 * [Passkeys](passkeys.md) – Sign in with your fingerprint, face, screen lock, or a hardware security key
 * [GitHub single sign-on](github-single-sign-on.md) – Sync your Argos team with a GitHub organization
 * [SAML single sign-on](saml-single-sign-on.md) – Enforce single sign-on through your SAML identity provider

docs/learn/account-and-access/account-management.md

@@ -44,7 +44,7 @@ Choose **Import a Git repository** and select a Git provider (GitHub or GitLab)
 {% tab title="Create without Git" %}
 Choose **Create a project without Git**, enter a **Project name**, and select **Create project**.
 
-A project without a connected repository still receives builds through the [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md) using its project token. Features that depend on a repository — such as pull request comments — become available once you link one.
+A project without a connected repository still receives builds through the [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md) using a [project token](project-tokens.md). Features that depend on a repository — such as pull request comments — become available once you link one.
 {% endtab %}
 {% endtabs %}
 
@@ -68,7 +68,7 @@ Only project admins can delete a project. To keep it under another account inste
 2. On the **Delete Project** card, select **Delete**.
 3. Type the project's full name (`account/project`), then `delete my project`, and select **Delete**.
 
-Argos warns that this can't be undone. Once the project is deleted, uploads with its project token fail and Argos stops updating its commit statuses. If the Argos check is a required status check in your Git provider, remove it there, or open pull requests keep waiting for it.
+Argos warns that this can't be undone. Once the project is deleted, uploads with its project tokens fail and Argos stops updating its commit statuses. If the Argos check is a required status check in your Git provider, remove it there, or open pull requests keep waiting for it.
 
 ### Uninstall the GitHub App
 

docs/learn/account-and-access/project-tokens.md

@@ -0,0 +1,179 @@
+---
+description: "Create the project tokens CI uses to upload to Argos, choose their permissions and expiration, and rotate them without downtime."
+---
+
+# Project tokens
+
+A project token authenticates your CI with Argos. Store it as a CI secret and expose it as the `ARGOS_TOKEN` environment variable: the Argos SDK and CLI use it to upload builds and deployments, and to read project data.
+
+A project can have several tokens. Each one has:
+
+* a **name**, to recognize where it is used, such as "GitHub Actions";
+* the **projects** it is linked to: usually one, or several projects of the same account;
+* its **permissions**, which decide what it can do on those projects;
+* an **expiration** date, or none;
+* a **last used** date, refreshed when CI authenticates with it.
+
+Argos shows a token once, when it is created, and only stores a hash of it. Nobody can display it again, administrators included. If you lose a token, create a new one and revoke the old one.
+
+{% hint style="info" %}
+On GitHub Actions, you can skip the token: [OIDC or tokenless authentication](../integrations/github-actions-authentication.md) authenticates uploads without a secret to store or rotate.
+{% endhint %}
+
+### Where tokens are managed
+
+Tokens belong to the account, team or personal, that owns the projects.
+
+* **Project settings → Authentication**, on the **Project tokens** card, lists the tokens linked to the project, including tokens linked to other projects too. [Project reviewers and administrators](team-members-and-roles.md) see the list. Project administrators create tokens for the project, and rename or revoke the tokens linked only to projects they administer.
+* **Team Settings → Tokens** lists every project token of the team. Team owners create, rename and revoke any of them there, including tokens linked to several projects. On a personal account, the same list is in your account's **Settings → Tokens**.
+
+The list shows each token's name, permissions, other linked projects, and when it was created, last used, and expires. It never shows the token itself.
+
+### Create a token
+
+{% stepper %}
+{% step %}
+
+### Open the token settings
+
+For a token used by one project, open the project's **Settings → Authentication** and, on the **Project tokens** card, select **Create token**.
+
+For a token linked to several projects, open **Team Settings → Tokens** and select **Create token**.
+{% endstep %}
+
+{% step %}
+
+### Name the token
+
+Enter a **Token name** that says where the token is used, such as "GitHub Actions". In team settings, also tick the **Projects** to link it to.
+{% endstep %}
+
+{% step %}
+
+### Choose its permissions and expiration
+
+The defaults, **Upload from CI** and **90 days**, let CI upload builds and deployments, but not media. See [Permissions](#permissions) and [Expiration](#expiration) to change them.
+{% endstep %}
+
+{% step %}
+
+### Copy the token
+
+Select **Create token**. Argos shows the token once: copy it right away and store it as the `ARGOS_TOKEN` secret in your CI.
+{% endstep %}
+{% endstepper %}
+
+When you set up a new project, the **Getting started** page has a **Generate token** button. It creates a token named "Getting started", with the **Upload from CI** permissions, that expires in 90 days, and fills it into the commands on the page. Only project administrators see the button; other contributors are asked to get a token from an administrator.
+
+### Permissions
+
+When you create a token, choose a preset, or **Advanced** to tick individual permissions.
+
+| Preset                       | Permissions                         | Use it to                                                                                       |
+| ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
+| **Upload from CI** (default) | `builds:write`, `deployments:write` | Upload builds and deployments from CI, but not media.                                           |
+| **Read only**                | `projects:read`, `media:read`       | Read builds, screenshot diffs, tests, deployments and media, for example with the [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md). |
+| **Full access**              | All five permissions                | Upload builds and deployments, read projects, and upload or delete media.                       |
+| **Advanced**                 | The ones you tick                   | Combine permissions yourself.                                                                   |
+
+| Permission          | Shown as           | Allows the token to                                              |
+| ------------------- | ------------------ | ---------------------------------------------------------------- |
+| `builds:write`      | Upload builds      | Create, update and finalize builds and their screenshots.        |
+| `deployments:write` | Upload deployments | Create and finalize deployments.                                 |
+| `projects:read`     | Read projects      | Read builds, screenshot diffs, tests and deployments.            |
+| `media:read`        | Read media         | Read the images and videos uploaded to the projects.             |
+| `media:write`       | Upload media       | Upload images and videos, and delete the ones already uploaded.  |
+
+Two uses need more than one preset covers:
+
+* [Uploading standalone media](../media/standalone-media-upload.md) needs **Upload media**, which **Upload from CI** doesn't include.
+* [`argos baseline download`](../../sdks-reference/argos-command-line-interface-cli.md#downloading-screenshots-and-baselines) needs both **Read projects** and **Upload builds**.
+
+Pick the permissions under **Advanced**, or use **Full access**.
+
+A request that needs a permission the token lacks fails with a `403` error: "This project token lacks a permission. This endpoint requires: …", followed by the missing permission.
+
+### Expiration
+
+A new token expires in **90 days** by default. You can also pick 30, 60 or 180 days, 1 year, or **No expiration**. The dialog shows the date CI will stop uploading: [rotate the token](#rotate-a-token-without-downtime) before then.
+
+**No expiration** is discouraged. Such a token stays valid until someone revokes it, so if it leaks, in a CI log, a forked workflow or a former teammate's machine, whoever holds it can upload to your projects for as long as nobody notices. Argos asks you to confirm before creating one.
+
+Once a token has expired, its date shows as **Expired** in the list, and uploads with it fail with "This project token has expired, create a new one."
+
+### Rotate a token without downtime
+
+A project can have several tokens, so you can create a replacement before you revoke a token, and CI always has a valid one.
+
+{% stepper %}
+{% step %}
+
+### Create the replacement
+
+[Create a token](#create-a-token) with the same projects and permissions as the old one.
+{% endstep %}
+
+{% step %}
+
+### Update the CI secret
+
+Replace the value of the `ARGOS_TOKEN` secret with the new token, in every CI that uses the old one.
+{% endstep %}
+
+{% step %}
+
+### Wait for the old token to go quiet
+
+Watch the **Last used** date of both tokens. Argos refreshes it within a few minutes of each use. Once the old token's date stops moving while the new one's keeps updating, nothing uses the old token anymore.
+{% endstep %}
+
+{% step %}
+
+### Revoke the old token
+
+Open the old token's menu, select **Revoke**, and confirm. Anything still using it is rejected from its next upload.
+{% endstep %}
+{% endstepper %}
+
+Rotate a token before it expires, and when someone who had access to it leaves. If a token leaks, revoke it right away, without waiting for its last used date: uploads fail until CI has the replacement, but nobody else can use it.
+
+### Use a token linked to several projects
+
+A token linked to several projects doesn't tell Argos which project an upload is for. Set `ARGOS_PROJECT` to the project's full name, `owner/project`, next to `ARGOS_TOKEN`:
+
+{% code title=".github/workflows/argos.yml" %}
+```yaml
+env:
+  ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+  ARGOS_PROJECT: my-team/my-project
+```
+{% endcode %}
+
+Without it, the upload fails with "This project token is linked to several projects. Pass `project` as `owner/project` (`ARGOS_PROJECT` in the SDK) to choose one." A token linked to a single project doesn't need `ARGOS_PROJECT`, and ignores it if it is set.
+
+When you [transfer a project](../billing-and-subscription/how-to-subscribe.md#transfer-your-projects) to another account, the tokens linked only to that project move with it. A token linked to other projects too stays with the former account and stops working for the transferred project.
+
+### Legacy tokens
+
+Tokens created before Argos supported several tokens per project are listed as **Legacy token**. They keep every permission, never expire, and keep working: CI that uses one needs no change. Their **Last used** date reads **Never** until CI next uses them.
+
+To limit what a legacy token can do, [rotate it](#rotate-a-token-without-downtime) to a token with **Upload from CI** permissions and an expiration date.
+
+### Manage tokens from the CLI or the API
+
+The [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md#configuring-a-project) lists, creates and revokes tokens with `argos project token` and, for every token of an account, `argos account project-token`. Both call the [Argos REST API](https://argos-ci.com/docs/api-reference) endpoints below, which authenticate with a [personal access token](../../sdks-reference/argos-command-line-interface-cli.md#project-tokens-and-personal-access-tokens) or OAuth, not with a project token.
+
+| Endpoint                                                  | Does                                                    | Requires                                                                  |
+| --------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `GET /projects/{owner}/{project}/tokens`                  | Lists the tokens linked to a project.                   | Reviewer role on the project.                                             |
+| `POST /projects/{owner}/{project}/tokens`                 | Creates a token linked to the project.                  | Administrator of the project.                                             |
+| `DELETE /projects/{owner}/{project}/tokens/{tokenId}`     | Revokes a token linked to the project.                  | Administrator of every project the token is linked to, or of the account. |
+| `GET /accounts/{accountSlug}/project-tokens`              | Lists every project token of the account.               | Administrator of the account.                                             |
+| `POST /accounts/{accountSlug}/project-tokens`             | Creates a token linked to the listed `projects`.        | Administrator of the account, or of every listed project.                 |
+| `DELETE /accounts/{accountSlug}/project-tokens/{tokenId}` | Revokes a token of the account.                         | Administrator of the account, or of every project the token is linked to. |
+
+The create endpoints take a `name`, an optional `permissions` list, and a required `expireAt`: an ISO 8601 date, or `null` for a token that never expires. Without `permissions`, the token gets `builds:write` and `deployments:write`, like **Upload from CI**. The token's value is only in the response to its creation, in the `token` field.
+
+The CLI sends `expireAt: null` unless you pass `--expires-in <days>` or `--expire-at <date>`, so its tokens never expire by default: pass one of them.
+
+The [Argos MCP server](../../agents/mcp-server.md) exposes the same operations as tools, so an AI agent can create, list and revoke project tokens with the permissions you grant it.