Authentication

Tampa.dev uses OAuth 2.1 with PKCE for authorization. This is the recommended flow for all applications - both server-side and single-page apps.

Authorization Flow

Register an application in the Developer Portal
Generate a PKCE code verifier and challenge
Redirect the user to: https://tampa.dev/oauth/authorize
User approves your app and is redirected back with an authorization code
Exchange the code for tokens at: https://tampa.dev/oauth/token
Use the access token to call API endpoints on https://api.tampa.dev: Authorization: Bearer <token>

Authorization URL Parameters

Parameter	Required	Description
`response_type`	Yes	Must be `code`
`client_id`	Yes	Your app's client ID
`redirect_uri`	Yes	One of your registered redirect URIs
`scope`	Yes	Space-separated list of scopes
`code_challenge`	Yes	PKCE code challenge (S256)
`code_challenge_method`	Yes	Must be `S256`
`state`	Recommended	Random string to prevent CSRF

Token Exchange

After the user approves, exchange the authorization code for tokens:

curl -X POST https://tampa.dev/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_HERE" \
  -d "redirect_uri=https://myapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

The response includes an access_token and refresh_token.

Authentication Methods

All API endpoints accept three authentication methods:

Method	Header	Use Case
OAuth Bearer Token	`Authorization: Bearer <access_token>`	Third-party apps, integrations
Personal Access Token	`Authorization: Bearer td_pat_...`	CLI tools, scripts, CI/CD
Session Cookie	`Cookie: session=...`	Tampa.dev web application

This includes management endpoints (group settings, event creation, badge management, etc.) which require the appropriate manage:* scope when using OAuth or PAT authentication. See Scopes for details.

MCP (AI Agent) Authentication

Tampa.dev also supports the Model Context Protocol (MCP), allowing AI assistants and automation tools to interact with the platform. MCP clients authenticate using the same methods above:

OAuth 2.1: MCP clients discover the server via GET /.well-known/mcp-configuration, register dynamically, and obtain tokens through the standard OAuth flow. This is MCP's preferred authentication method.
Personal Access Tokens: For simpler setups, configure your AI assistant with a PAT.