Authentication

The Expensicat API supports two authentication methods: Bearer tokens for direct access and OAuth2 for third-party integrations.

Bearer token

Include your token in the Authorization header:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.expensicat.com/api/v1/transactions

Bearer tokens can be session JWTs or OAuth2 access tokens.

OAuth2 (Authorization Code + PKCE)

For third-party applications, use the OAuth2 authorization code flow with PKCE.

1. Redirect to authorize

GET /api/auth/oauth2/authorize

Parameter	Description
`client_id`	Your application's client ID
`redirect_uri`	Your registered callback URL
`response_type`	Must be `code`
`scope`	Space-separated list of scopes
`code_challenge`	PKCE code challenge (S256)
`code_challenge_method`	Must be `S256`
`state`	Random string to prevent CSRF

2. Exchange code for token

POST /api/auth/oauth2/token

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "redirect_uri": "https://yourapp.com/callback",
  "client_id": "YOUR_CLIENT_ID",
  "code_verifier": "PKCE_CODE_VERIFIER"
}

The response includes an access_token and refresh_token.

3. Use the access token

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.expensicat.com/api/v1/transactions

Scopes

Request only the scopes your application needs:

Scope	Description
`transactions:read`	Read transactions
`transactions:write`	Create and update transactions
`entries:read`	Read entries, projects, time entries
`entries:write`	Create and update entries, projects, time entries
`invoices:read`	Read invoices, customers, recurring invoices
`invoices:write`	Create and update invoices, customers, recurring invoices
`banking:read`	Read bank accounts
`banking:write`	Manage bank account connections
`documents:read`	Read documents
`documents:write`	Upload and manage documents
`team:read`	Read team members, organization settings, integrations
`team:admin`	Manage team members, organization settings, integrations
`analytics:read`	Read financial metrics and reports