OAuth authentication flow — TaxMaxi Auth API

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.

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"
}

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.

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

string

required

The OAuth provider to authorize with, e.g. coinbase.

Query parameters

string

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

Response — 200 OK

string

required

The full URL to redirect the user to for OAuth authorization.

string

required

A CSRF-protection token. In the polling flow, use this value as the id when calling GET /auth/oauth/:id.

Errors

Status	Error	Description
404	`ProviderNotFoundError`	The 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

string

required

The OAuth provider, e.g. coinbase.

Query parameters

string

required

The authorization code from the OAuth provider.

string

required

The state parameter for CSRF validation. Must match the value returned by /auth/authorize/:provider.

string

An error code from the provider if authorization failed.

string

A human-readable description of the provider error.

Response — 200 OK

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

Errors

Status	Error	Description
400	`OAuthStateInvalidError`	The `state` parameter does not match. Restart the OAuth flow.
401	`ProviderAuthError`	The OAuth provider rejected the authorization code.
404	`ProviderNotFoundError`	The 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.

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.

User authorizes in the browser

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

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

string

required

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

Response — 200 OK

string

required

The OAuth session ID.

string

required

The OAuth provider for this session.

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

string

The OAuth authorization URL, if still available.

string

The session bearer token. Only present when status is "completed". Use this as Authorization: Bearer <sessionToken> on protected requests.

string

The authenticated user’s ID. Only present when status is "completed".

string

A human-readable message, present when status is "failed" or "expired".

string

required

ISO 8601 timestamp when this OAuth session expires.

Errors

Status	Error	Description
401	`ProviderAuthError`	The OAuth provider returned an error for this session.

curl --request GET \
  "https://api.taxmaxi.com/auth/authorize/coinbase"

curl --request GET \
  "https://api.taxmaxi.com/auth/oauth/STATE_VALUE_HERE"

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.

Auth

Sources

Legal References

OAuth authentication flow — TaxMaxi Auth API

Browser redirect flow

GET /auth/authorize/:provider

Path parameters

Query parameters

Response — 200 OK

Errors

GET /auth/callback/:provider

Path parameters

Query parameters

Response — 200 OK

Errors

Polling flow (CLI and headless environments)

GET /auth/oauth/:id

Path parameters

Response — 200 OK

Errors

​Browser redirect flow

​GET /auth/authorize/:provider

​Path parameters

​Query parameters

​Response — 200 OK

​Errors

​GET /auth/callback/:provider

​Path parameters

​Query parameters

​Response — 200 OK

​Errors

​Polling flow (CLI and headless environments)

​GET /auth/oauth/:id

​Path parameters

​Response — 200 OK

​Errors

Browser redirect flow

GET /auth/authorize/:provider

Path parameters

Query parameters

Response — 200 OK

Errors

GET /auth/callback/:provider

Path parameters

Query parameters

Response — 200 OK

Errors

Polling flow (CLI and headless environments)

GET /auth/oauth/:id

Path parameters

Response — 200 OK

Errors