# Argos auth.md

How AI agents and automated clients authenticate to [Argos](https://argos-ci.com),
the visual testing platform.

## Who this is for

Agents calling the [Argos REST API](https://argos-ci.com/docs/api-reference) (`https://api.argos-ci.com/v2`) or
connecting to the [Argos MCP server](https://argos-ci.com/docs/agents/mcp-server) (`https://mcp.argos-ci.com`). Both
accept the same bearer tokens, issued by the Argos authorization server at
`https://app.argos-ci.com`.

Argos accounts belong to people: an agent always acts on behalf of a user who
signs in and grants it access. Registration is open to anonymous agents, and
the resulting client can do nothing until a user claims it by granting consent.

## 1. Discover

- Authorization server metadata (RFC 8414): `https://app.argos-ci.com/.well-known/oauth-authorization-server`
- Protected resource metadata (RFC 9728): `https://api.argos-ci.com/.well-known/oauth-protected-resource` and `https://mcp.argos-ci.com/.well-known/oauth-protected-resource`
- API catalog (RFC 9727): `https://argos-ci.com/.well-known/api-catalog`
- MCP server card: `https://mcp.argos-ci.com/.well-known/mcp/server-card.json`

## 2. Register

`POST https://app.argos-ci.com/oauth/register` with your client metadata (RFC 7591
dynamic client registration). No credentials or pre-existing identity are
required. The response carries your `client_id`.

```http
POST /oauth/register HTTP/1.1
Host: app.argos-ci.com
Content-Type: application/json

{
  "client_name": "My Agent",
  "redirect_uris": ["http://127.0.0.1:8976/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

## 3. Claim

Send the user to `https://app.argos-ci.com/oauth/authorize` to run the authorization
code flow with PKCE (`S256`). They sign in, choose which organizations to
share, and grant scopes. This is what turns an anonymous registration into an
authorized client.

## 4. Exchange

`POST https://app.argos-ci.com/oauth/token` with the authorization code and your PKCE
verifier to receive an `access_token` and a `refresh_token`. Refresh tokens
are supported; use them rather than sending the user through consent again.

## 5. Use

Send the token as a bearer credential:

```http
Authorization: Bearer <access_token>
```

### Scopes

- `profile` — Read your Argos profile and the list of teams you belong to.
- `projects:read` — Read your projects, builds, screenshots, diffs, tests, and analytics.
- `projects:write` — Create and configure projects and their settings.
- `builds:write` — Create and upload builds and screenshots.
- `reviews:write` — Approve, reject, or dismiss build reviews and ignore changes.
- `comments:read` — Read build comments and threads.
- `comments:write` — Post, edit, and delete comments, add reactions, and manage subscriptions.
- `media:read` — Read the images and videos uploaded to your teams.
- `media:write` — Upload images and videos, and delete the ones already uploaded.
- `account:admin` — Manage organization settings and members.

Scopes only ever narrow what the authenticating user is already allowed to do —
they never widen it.

## 6. Revoke

- Revoke a token at `https://app.argos-ci.com/oauth/revoke` (RFC 7009).
- Users revoke an agent's access at any time from **Authorized applications**
  in their Argos settings. Treat a `401` as "re-run the flow from step 3".

## Alternative: personal access token

Where OAuth is impractical, a user can create a personal access token in their
Argos settings and hand it to the agent. It is used the same way (step 5). See
the [API reference](https://argos-ci.com/docs/api-reference).

## Support

Rate limits are documented in the [API reference](https://argos-ci.com/docs/api-reference).
Questions: contact@argos-ci.com or https://argos-ci.com/discord.