# auth.md

Agent registration and authentication for the Tommy & Spartan platform.

> **Tommy** is a marketing director, built as software. **Spartan** is a strategy
> director, built the same way. Senior partners sign off on every output. This
> document tells AI agents how to authenticate against the Tommy & Spartan
> platform APIs and MCP server.

## Availability

- **Status:** pre-GA. The public API, MCP server, and authorisation server
  described here go live at **General Availability on 2026-07-31**.
- Discovery metadata is published now so agents and clients can integrate ahead
  of GA. Endpoints below begin serving traffic at GA.
- Until GA, the way to engage is the published Agent Skills
  (`/.well-known/agent-skills/`) and the human application at
  <https://tommyspartan.com/founding-20>.

## Audience

This file is for autonomous AI agents and integrators that need programmatic,
authenticated access to the Tommy & Spartan platform (account engagement, the
MQL-to-SQL engine, and the MCP server).

## How agents register

Registration uses **OAuth 2.0**. Two flows are supported:

1. **Client Credentials** (service-to-service agents)
   - Register: `POST https://auth.tommyspartan.com/oauth/register`
   - Token: `POST https://auth.tommyspartan.com/oauth/token`
   - Use the issued bearer token in `Authorization: Bearer <token>`.
2. **Authorization Code + PKCE** (agents acting for a signed-in human)
   - Authorize: `https://auth.tommyspartan.com/oauth/authorize`
   - Token: `https://auth.tommyspartan.com/oauth/token`

Authorisation-server metadata: <https://tommyspartan.com/.well-known/oauth-authorization-server>
Protected-resource metadata: <https://tommyspartan.com/.well-known/oauth-protected-resource>

```json agent_auth
{
  "skill": "engage-tommy-spartan",
  "register_uri": "https://auth.tommyspartan.com/oauth/register",
  "supported_identity_types": ["identity_assertion", "anonymous"],
  "supported_credential_types": ["access_token"],
  "claim_uri": "https://auth.tommyspartan.com/oauth/claims",
  "revocation_uri": "https://auth.tommyspartan.com/oauth/revoke",
  "scopes_supported": ["agent.read", "agent.invoke", "mcp"],
  "status": "pre-ga",
  "activation": "2026-07-31"
}
```

## Scopes

| Scope | Grants |
|-------|--------|
| `agent.read` | Read public account-engagement and catalogue resources |
| `agent.invoke` | Invoke the MQL-to-SQL engine for a named account |
| `mcp` | Connect to the Tommy & Spartan MCP server |

## Contact

Email: <mike@tokenomik.com>