Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.taxmaxi.com/llms.txt

Use this file to discover all available pages before exploring further.

TaxMaxi supports OAuth for providers like Coinbase. Two flows are available: a browser redirect flow for web applications, and a polling flow for CLI and headless environments where you cannot intercept a redirect. Both flows start at GET /auth/authorize/:provider and end with a session token you use to authenticate all subsequent requests.

​
Browser redirect flow

In a browser context, you redirect the user to the provider’s authorization page and handle the callback when they return.
1

Get the authorization URL

Call GET /auth/authorize/:provider to retrieve the URL to redirect your user to. Save the state value — you will need it to verify the callback.
curl --request GET \
  "https://api.taxmaxi.com/auth/authorize/coinbase?redirectTo=/dashboard"

{
  "redirectUrl": "https://login.coinbase.com/oauth2/auth?client_id=...&state=abc123",
  "state": "abc123"
}
2

Redirect the user

Send the user to the redirectUrl. After they grant access, the provider redirects them to /auth/callback/coinbase with code and state query parameters.
3

Exchange the code for a session

The callback endpoint automatically exchanges the authorization code for a session token. The response has the same shape as POST /auth/login.
{
  "token": "sess_01HXYZ...",
  "user": {
    "id": "usr_01HXYZ...",
    "email": "[email protected]",
    "displayName": "Max Mustermann"
  },
  "provider": "coinbase",
  "expiresAt": "2026-06-14T10:00:00.000Z"
}

​
GET /auth/authorize/:provider

Returns an authorization URL and a state value. Redirect the user to redirectUrl to start the OAuth flow.

​
Path parameters

​
provider
string
required
The OAuth provider to authorize with, e.g. coinbase.

​
Query parameters

​
redirectTo
string
An optional frontend-relative path to navigate to after the browser-based OAuth flow completes (e.g. /dashboard).

​
Response — 200 OK

​
redirectUrl
string
required
The full URL to redirect the user to for OAuth authorization.
​
state
string
required
A CSRF-protection token. In the polling flow, use this value as the id when calling GET /auth/oauth/:id.

​
Errors

StatusErrorDescription
404ProviderNotFoundErrorThe specified provider is not enabled. The provider field confirms which one was requested.

​
GET /auth/callback/:provider

Handles the OAuth provider redirect. The provider calls this endpoint automatically with a code and state after the user authorizes. It exchanges the code for tokens and returns a session.

​
Path parameters

​
provider
string
required
The OAuth provider, e.g. coinbase.

​
Query parameters

​
code
string
required
The authorization code from the OAuth provider.
​
state
string
required
The state parameter for CSRF validation. Must match the value returned by /auth/authorize/:provider.
​
error
string
An error code from the provider if authorization failed.
​
error_description
string
A human-readable description of the provider error.

​
Response — 200 OK

Same as POST /auth/login: returns token, user, provider, and expiresAt.

​
Errors

StatusErrorDescription
400OAuthStateInvalidErrorThe state parameter does not match. Restart the OAuth flow.
401ProviderAuthErrorThe OAuth provider rejected the authorization code.
404ProviderNotFoundErrorThe specified provider is not enabled.

​
Polling flow (CLI and headless environments)

When you cannot intercept a browser redirect — for example in a terminal CLI — show the user the redirectUrl and poll for completion using the state value as the session ID.
1

Get the authorization URL

Call GET /auth/authorize/coinbase and display the redirectUrl to the user so they can open it in a browser. Record the state value.
2

User authorizes in the browser

The user opens the URL, grants access, and the provider redirects back to TaxMaxi automatically.
3

Poll for completion

Poll GET /auth/oauth/:id (where :id is the state from step 1) until status is "completed". The sessionToken field contains your bearer token.
curl --request GET \
  "https://api.taxmaxi.com/auth/oauth/abc123"

{
  "id": "abc123",
  "provider": "coinbase",
  "status": "completed",
  "sessionToken": "sess_01HXYZ...",
  "userId": "usr_01HXYZ...",
  "authorizationUrl": null,
  "message": null,
  "expiresAt": "2026-06-14T10:00:00.000Z"
}

​
GET /auth/oauth/:id

Returns the current status of an OAuth session. Use this to poll for completion in headless or CLI flows.

​
Path parameters

​
id
string
required
The OAuth session ID. This is the state value returned by GET /auth/authorize/:provider.

​
Response — 200 OK

​
id
string
required
The OAuth session ID.
​
provider
string
required
The OAuth provider for this session.
​
status
string
required
The current session status. One of:
  • pending — the user has not yet authorized in the browser
  • completed — authorization succeeded; sessionToken and userId are populated
  • failed — the authorization was rejected or an error occurred
  • expired — the session window has passed; restart the flow
​
authorizationUrl
string
The OAuth authorization URL, if still available.
​
sessionToken
string
The session bearer token. Only present when status is "completed". Use this as Authorization: Bearer <sessionToken> on protected requests.
​
userId
string
The authenticated user’s ID. Only present when status is "completed".
​
message
string
A human-readable message, present when status is "failed" or "expired".
​
expiresAt
string
required
ISO 8601 timestamp when this OAuth session expires.

​
Errors

StatusErrorDescription
401ProviderAuthErrorThe OAuth provider returned an error for this session.
curl --request GET \
  "https://api.taxmaxi.com/auth/authorize/coinbase"
Poll GET /auth/oauth/:id every 2–3 seconds. Stop polling when status is "completed", "failed", or "expired". If the session expires, restart from GET /auth/authorize/:provider.