Authentication: sessions, OAuth, and token refresh

TaxMaxi uses session tokens for authentication. When you log in, the API returns a token that you attach to every subsequent request as a Bearer token in the Authorization header. Tokens have an expiration time and can be refreshed without logging in again. For Coinbase integration, TaxMaxi also supports an OAuth flow that the CLI handles automatically, but you can drive it yourself via the API if needed.

Register

Send POST /auth/register with your email, a password of at least 8 characters, and an optional display name:

curl -X POST https://api.taxmaxi.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "displayName": "Your Name"
  }'

The request body fields are:

Field	Type	Required	Description
`email`	string	Yes	Your email address
`password`	string	Yes	Minimum 8 characters
`displayName`	string	No	Display name shown in your profile

A successful 201 response starts the email verification flow:

{
  "email": "[email protected]",
  "redirectTo": "/verify-email"
}

If the email is already registered, you receive a 409 error. If the password is too short or weak, you receive a 400 error with a list of unmet requirements.

Verify your email

After registration, TaxMaxi sends a verification code to your email. Submit it to POST /auth/verify-email:

curl -X POST https://api.taxmaxi.com/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

Field	Type	Required	Description
`code`	string	Yes	The verification code from your email

A successful response returns a redirectTo path indicating your account is verified and you can proceed to log in. If the code is invalid or has expired, you receive a 400 error. To resend a code, call POST /auth/resend-verification with no body.

You cannot log in with your local credentials until your email is verified. Attempting to do so returns a 403 response indicating verification is required.

Log in

Authenticate with POST /auth/login. For a local (email and password) account, set provider to "local" and pass your credentials in the credentials object:

curl -X POST https://api.taxmaxi.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "local",
    "credentials": {
      "email": "[email protected]",
      "password": "your-password"
    }
  }'

A successful response:

{
  "token": "sess_abc123...",
  "user": {
    "id": "usr_...",
    "email": "[email protected]",
    "displayName": "Your Name"
  },
  "provider": "local",
  "expiresAt": "2026-06-14T00:00:00.000Z"
}

Field	Description
`token`	Session token — attach this to all authenticated requests
`user`	The authenticated user object
`provider`	The provider used for this login
`expiresAt`	ISO 8601 timestamp when the session expires

Authenticate requests

Pass the session token as a Bearer token on every request that requires authentication:

curl https://api.taxmaxi.com/auth/me \
  -H "Authorization: Bearer sess_abc123..."

All protected endpoints return 401 Unauthorized if the token is missing, invalid, or expired.

Refresh a session

To extend a session without logging in again, call POST /auth/refresh while you still have a valid token:

curl -X POST https://api.taxmaxi.com/auth/refresh \
  -H "Authorization: Bearer sess_abc123..."

{
  "token": "sess_newtoken...",
  "expiresAt": "2026-07-14T00:00:00.000Z"
}

The response includes a new token and updated expiresAt. Replace your stored token with the new one.

OAuth with Coinbase

To connect a Coinbase account, TaxMaxi uses an OAuth flow. The easiest way to run it is with the CLI:

tax coinbase connect

If you need to drive the flow from your own application:

Call GET /auth/authorize/coinbase to get an authorization URL:

curl https://api.taxmaxi.com/auth/authorize/coinbase

{
  "redirectUrl": "https://login.coinbase.com/oauth2/auth?...",
  "state": "csrf_state_value"
}

Redirect your user to redirectUrl.
After the user authorizes, poll GET /auth/oauth/:id (where :id is the OAuth session identifier from the authorization response) to check the flow status:

curl https://api.taxmaxi.com/auth/oauth/oauth_session_id

{
  "id": "oauth_session_id",
  "provider": "coinbase",
  "status": "completed",
  "authorizationUrl": null,
  "sessionToken": "sess_abc123...",
  "userId": "usr_...",
  "message": null,
  "expiresAt": "2026-06-14T00:00:00.000Z"
}

The status field cycles through "pending", "completed", "failed", or "expired". When status is "completed", use the sessionToken as your Bearer token for subsequent requests.

Log out

Invalidate the current session with POST /auth/logout:

curl -X POST https://api.taxmaxi.com/auth/logout \
  -H "Authorization: Bearer sess_abc123..."

{
  "success": true
}

Error reference

Status	Meaning
`400`	Validation error — check `message` and `field` in the response body
`400`	Verification code invalid or expired
`400`	Password does not meet minimum requirements
`401`	Invalid credentials or session token
`401`	Session expired — refresh or log in again
`403`	Email not yet verified — complete verification before logging in
`409`	Email already registered

Get Started

CLI

JavaScript SDK

Core Concepts

Authentication: sessions, OAuth, and token refresh

Register

Verify your email

Log in

Authenticate requests

Refresh a session

OAuth with Coinbase

Log out

Error reference

​Register

​Verify your email

​Log in

​Authenticate requests

​Refresh a session

​OAuth with Coinbase

​Log out

​Error reference

Register

Verify your email

Log in

Authenticate requests

Refresh a session

OAuth with Coinbase

Log out

Error reference