---
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 workspace bearer tokens provisioned through authenticated MCP or the dashboard 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 or GitHub.
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 on the cache API. Use the authenticated MCP server's
`create_token` tool to mint a workspace token, or have a human create one in the
dashboard (https://app.cachely.dev) and supply it directly 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

- MCP `create_token` returns the raw credential to the coding agent, so its
  provider may process it under its own terms. Offer dashboard provisioning
  and manual entry into an ignored file or CI secret store when the user wants
  to keep the raw credential out of the agent conversation. In that mode, use
  placeholders and do not call `create_token` or read the secret file.
- 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.