# auth.md

Agent registration and authentication for Amdahl.

One API for self-improving GTM agents. Amdahl grades what your agents write against your own won, lost, and stalled deals, then turns the misses into prompt fixes. Every claim ships with a citation. SOC 2 Type 2.

This document is for AI agents (and the developers wiring them up)
that want authenticated access to Amdahl's MCP server and REST API.
Both surfaces share one authorization server and one credential model.

## Who this is for

- MCP clients connecting to https://app.amdahl.ai/mcp
- Server-side agents calling https://app.amdahl.ai/api/platform/v1

All access is workspace-scoped: a credential belongs to one Amdahl
workspace and is re-checked against live workspace membership on every
request. There is no unattended agent-only grant -- a human member
approves access once in a browser consent step.

## Discovery

- Authorization server metadata (RFC 8414):
  https://app.amdahl.ai/.well-known/oauth-authorization-server
- Protected resource metadata (RFC 9728):
  https://app.amdahl.ai/.well-known/oauth-protected-resource
- MCP server card: https://amdahl.ai/.well-known/mcp.json
- Agent skills index: https://amdahl.ai/.well-known/agent-skills/index.json

The authorization server metadata carries an `agent_auth` block whose
`skill` URL points at the step-by-step registration skill
(amdahl-agent-auth) in the skills index above.

## Method 1: OAuth 2.1 with dynamic client registration

1. Register a client (RFC 7591, anonymous, rate limited):

       POST https://app.amdahl.ai/oauth/register
       {
         "client_name": "My Agent",
         "redirect_uris": ["https://agent.example.com/callback"]
       }

   Returns a public `client_id`; `token_endpoint_auth_method` is
   `none`. Redirect URIs must be https (http allowed on localhost
   only).

2. Authorize: send the user to https://app.amdahl.ai/oauth/authorize with
   `response_type=code`, your `client_id`, a registered
   `redirect_uri`, and a PKCE S256 `code_challenge` (required).
   The user signs in, selects a workspace, and consents. Requested
   scopes are clamped server-side to the customer-agent ceiling.

3. Exchange: `POST https://app.amdahl.ai/oauth/token` with
   `grant_type=authorization_code` and your `code_verifier`.
   Refresh with `grant_type=refresh_token`.

4. Use: send `Authorization: Bearer <access_token>` to the MCP
   endpoint or the REST API.

5. Revoke: `POST https://app.amdahl.ai/oauth/revoke` with the token
   (RFC 7009). Removing the user from the workspace also invalidates
   their tokens.

## Method 2: workspace API key

A workspace admin signs in at https://console.amdahl.ai and mints an API key
for server-to-server agents. The key is sent exactly like an access
token (`Authorization: Bearer <key>`) and carries a named scope
bundle chosen at mint time.

## After you authenticate

- MCP: connect to https://app.amdahl.ai/mcp (streamable HTTP) and call
  `tools/list` / `resources/list` to discover capabilities.
- REST: base URL https://app.amdahl.ai/api/platform/v1; OpenAPI reference
  at https://docs.amdahl.ai/openapi.json.

## Support

- Docs: https://docs.amdahl.ai
- Contact: hello@amdahl.ai