# auth.md — Formswrite Agent Authentication

Formswrite protects its public REST API (`https://api.formswrite.com/api/v1/*`) and its MCP server
(`https://mcp.formswrite.com/mcp`) with a JSON Web Token (JWT) bearer credential.

## How to obtain a token
1. Create a Formswrite account and an organization at https://formswrite.com.
2. From the dashboard (https://formswrite.com/settings/api), generate an API token for the
   organization. This issues a long-lived (365 day) HS256 JWT.

## OAuth 2.1 (for agents / MCP clients)
Formswrite runs an OpenID Connect authorization server at `https://api.formswrite.com/oauth`.
Agents authenticate with the authorization_code + PKCE flow and may self-register
via dynamic client registration. Discover the endpoints at:

- https://formswrite.com/.well-known/openid-configuration
- https://formswrite.com/.well-known/oauth-authorization-server
- jwks: https://api.formswrite.com/oauth/jwks  (RS256 — verify access tokens against these keys)

Access tokens are RS256 JWTs scoped to the Formswrite API and MCP server.

## How to use a token
Send it as a bearer token on every request:

    Authorization: Bearer <jwt>

The same token authenticates both the REST API and the MCP server.

## Discovery metadata
- API catalog: https://formswrite.com/.well-known/api-catalog
- OpenAPI spec: https://formswrite.com/openapi.json
- Protected resource: https://formswrite.com/.well-known/oauth-protected-resource
- Authorization server: https://formswrite.com/.well-known/oauth-authorization-server
- MCP server card: https://mcp.formswrite.com/.well-known/mcp/server-card.json
- Agent skills: https://formswrite.com/.well-known/agent-skills/index.json

## agent_auth
- register_uri: https://formswrite.com/signup
- token_uri: https://formswrite.com/settings/api
- identity_types: ["organization"]
- credential_types: ["jwt_bearer"]
- bearer_methods: ["header"]