# Authenticating agents with Meso

This document explains how an AI agent obtains and uses credentials to call Meso's API on behalf of a user. It follows the WorkOS `auth.md` convention (https://github.com/workos/auth.md). Public, read-only resources — pricing, methodology, and everything under `/.well-known/` — need **no** authentication. Everything that touches a member's account (their program, logs, settings) requires a user-scoped access token.

Base API host: `https://api.meso.fitness`
Authorization server: `https://auth.meso.fitness`

## Discover

Start from the protected-resource metadata (RFC 9728):

- `https://meso.fitness/.well-known/oauth-protected-resource`

It lists `resource` (the API base) and `authorization_servers`. Fetch the authorization-server metadata (RFC 8414) from:

- `https://auth.meso.fitness/.well-known/oauth-authorization-server`

That document carries an `agent_auth` block describing agent-specific onboarding:

- `identity_endpoint` — where an agent presents or establishes its identity.
- `identity_types_supported` — one or more of `anonymous`, `identity_assertion`, `service_auth`.
- `identity_assertion.assertion_types_supported` — includes the ID-JAG token type `urn:ietf:params:oauth:token-type:id-jag` when identity-assertion is offered.
- `claim_endpoint` and `events_endpoint` — for claiming a delegated grant and receiving auth lifecycle events.

If you call the API without a token you will receive a `401` whose `WWW-Authenticate: Bearer resource_metadata="https://meso.fitness/.well-known/oauth-protected-resource"` header points you back here.

## Pick a method

- **anonymous** — for public endpoints (pricing, methodology). No token needed.
- **service_auth** — for a trusted backend acting as itself (no end user).
- **identity_assertion** — for an agent acting **on behalf of a user**, presenting an ID-JAG assertion (`urn:ietf:params:oauth:token-type:id-jag`) minted by an identity provider Meso trusts. Check `identity_assertion.assertion_types_supported` before minting so you know your assertion shape is accepted.

## Register

Register your client with the authorization server at `https://auth.meso.fitness` (dynamic client registration per RFC 7591 where enabled) to obtain a `client_id`. Redirect-based user consent uses the standard OAuth 2.1 authorization-code + PKCE flow.

## Claim

For delegated (on-behalf-of) access, present your identity assertion to the `identity_endpoint`, then claim the resulting grant at the `claim_endpoint`. The response references the scopes the user consented to.

## Exchange

Exchange the authorization code (or the claimed grant / ID-JAG assertion) for an `access_token` at the token endpoint advertised in the authorization-server metadata. Use PKCE. Tokens are short-lived; use the `refresh_token` to renew.

## Use the access_token

Send the token as a bearer credential on every API request:

```
GET https://api.meso.fitness/v1/program
Authorization: Bearer <access_token>
```

Respect the `scope` granted; requesting data outside your scope returns `403`.

## Errors

- `401 Unauthorized` — missing/expired token. The `WWW-Authenticate: Bearer resource_metadata=...` header tells you where to authenticate.
- `403 Forbidden` — valid token, insufficient scope.
- `400 invalid_request` / `invalid_grant` — malformed assertion or expired code; re-run Discover → Exchange.

## Revocation

Revoke a token at the revocation endpoint advertised in the authorization-server metadata, or when a user disconnects your agent. Subscribe to the `events_endpoint` to be notified when a grant is revoked so you can stop using cached tokens immediately.

---

> Note: the `api.meso.fitness` and `auth.meso.fitness` hosts are still in development. Until they are live, only the public, unauthenticated resources described above are reachable; use the Meso web app in the meantime.