---
name: cachely-authentication
description: Authenticate an autonomous agent with Cachely's protected APIs - OAuth 2.1 (dynamic client registration plus authorization-code with PKCE) for the MCP server, and human-provisioned workspace bearer tokens for the remote build cache API. Use when an agent needs to obtain and use credentials to call Cachely's MCP or cache endpoints.
---

# Cachely authentication

Cachely exposes two protected surfaces. Pick the one that matches your task.

## Discovery

- Protected Resource Metadata (RFC 9728): https://cachely.dev/.well-known/oauth-protected-resource
- Authorization Server Metadata (RFC 8414), incl. the `agent_auth` block: https://cachely.dev/.well-known/oauth-authorization-server
- Human/agent guide: https://cachely.dev/auth.md

The PRM `resource` and the AS `issuer` both resolve to `https://app.cachely.dev`.

## MCP server (`https://app.cachely.dev/mcp`) - OAuth 2.1, agent self-serve

Standard OAuth 2.1. No Cachely-specific grant.

1. Fetch the Authorization Server Metadata above; read `authorization_endpoint`,
   `token_endpoint`, `registration_endpoint`, and the `agent_auth` block.
   Cachely advertises a complete `oauth2_authorization_code_pkce` registration
   method (and no `identity_types_supported`, since the auth.md canonical
   identity types do not apply to its delegated authorization-code flow).
2. Register your client (RFC 7591): `POST https://app.cachely.dev/api/auth/mcp/register`
   with your `redirect_uris` to obtain a `client_id`.
3. Run the authorization-code flow with PKCE (`S256`) at
   `https://app.cachely.dev/api/auth/mcp/authorize`. The user signs in with Google.
4. Exchange the code and `code_verifier` at
   `https://app.cachely.dev/api/auth/mcp/token` for an access token (and refresh token).
5. Call `https://app.cachely.dev/mcp` with `Authorization: Bearer <access_token>`.

## Remote cache API (`https://remote.cachely.dev`) - bearer token

Agents cannot self-register here. A human creates a workspace token in the
dashboard (https://app.cachely.dev) and supplies it to the build tool or CI.
Send it as `Authorization: Bearer <token>` (Gradle and Bazel HTTP caches may
send it as the HTTP Basic password). See the `cachely-remote-cache` skill for
per-tool setup.

## Credential handling

- Treat every token as a secret; send it only over HTTPS in the `Authorization`
  header. Never log it, put it in a URL, or commit it.
- Prefer the shortest-lived credential that works: the refreshable OAuth access
  token for MCP, a scoped (ideally read-only) workspace token for the cache API.

## Not supported

Cachely does not implement ID-JAG identity assertions
(`urn:ietf:params:oauth:token-type:id-jag`), verified-email assertions, or
anonymous claim ceremonies, and runs no `/agent/identity`, claim, or revocation
endpoint. Do not attempt those flows.