# GainTrace auth.md

Machine-readable guidance for AI agents that want authorized access to
GainTrace on behalf of a user. GainTrace is an AI customer success platform;
the agent-facing service is the GainTrace MCP server.

## Agent audience

AI agents and MCP clients acting for a GainTrace workspace user (reading or
writing customer, health-score, revenue, and workflow data with that user's
consent). Anonymous agent access to customer data is not offered.

## Service endpoints

- MCP server (protected resource): `https://app.gaintrace.com/api/v1/mcp`
- Protected resource metadata (RFC 9728): `https://app.gaintrace.com/.well-known/oauth-protected-resource`
- Authorization server metadata (RFC 8414): `https://app.gaintrace.com/.well-known/oauth-authorization-server`
  (issuer: `https://app.gaintrace.com`)

## Registration and authorization

1. Register a client via OAuth 2.0 Dynamic Client Registration (RFC 7591):
   `POST https://app.gaintrace.com/api/auth/mcp/register`
2. Run the OAuth 2.0 authorization code flow with PKCE (S256) against the
   endpoints in the authorization server metadata. A human GainTrace user
   signs in and consents; agents cannot self-provision accounts.
3. Request only the scopes you need. Supported scopes are listed in the
   metadata documents (`read:*`, `write:*`, `use:trace_ai`, plus
   `openid profile email offline_access`).

## Credential use

- Send access tokens as `Authorization: Bearer <token>` headers (the only
  supported bearer method).
- Use `offline_access` + refresh tokens for long-lived agent sessions.
- Tokens are scoped to the authorizing user's workspace and permissions.

```json
{
  "agent_auth": {
    "skill": "oauth2-authorization-code-pkce",
    "register_uri": "https://app.gaintrace.com/api/auth/mcp/register",
    "methods": [
      {
        "type": "oauth2",
        "registration": "dynamic_client_registration",
        "grant_type": "authorization_code",
        "pkce": "S256",
        "authorization_server": "https://app.gaintrace.com",
        "resource": "https://app.gaintrace.com/api/v1/mcp",
        "bearer_methods": ["header"]
      }
    ]
  }
}
```

## Human signup

New workspaces are created by humans at <https://app.gaintrace.com/auth/login>
(email, Google, or Microsoft). Questions: <https://gaintrace.com/contact>.