Log in to your account — TaxMaxi Auth API

POST /auth/login accepts two login modes in a single endpoint, selected by the provider field. For the local provider you supply an email and password directly. For OAuth providers such as Coinbase, you supply the code and state values your application received from the OAuth callback — these are exchanged for a session token server-side. In both cases, a successful response includes a token that you pass as Authorization: Bearer <token> on all subsequent authenticated requests. Authenticates a user and returns a session token.

Request body

The shape of the credentials object depends on the provider you select.

Local (email + password)
OAuth (e.g. Coinbase)

string

required

Must be "local".

object

required

Hide credentials properties

string

required

The email address registered to the account.

string

required

The account password.

string

required

The OAuth provider name, e.g. "coinbase".

object

required

Hide credentials properties

string

required

The authorization code returned by the OAuth provider in the callback.

string

required

The state parameter from the OAuth callback, used to validate the flow.

Response — 200 OK

string

required

Your session token. Pass this as Authorization: Bearer <token> on all protected requests.

object

required

Show user properties

string

required

The unique identifier for the user.

string

required

The user’s email address.

string

The user’s display name, if set.

string

required

The provider used to authenticate, e.g. "local" or "coinbase".

string

required

ISO 8601 timestamp indicating when the session token expires. Refresh before this time using POST /auth/refresh.

Errors

Status	Error	Description
400	`AuthValidationError`	A required field is missing or malformed. The `field` property identifies which field failed.
400	`OAuthStateInvalidError`	The `state` parameter does not match the expected value. Restart the OAuth flow.
401	`AuthUnauthorizedError`	The email or password is incorrect.
401	`ProviderAuthError`	The OAuth provider rejected the authorization code. The `provider` and `reason` fields give more detail.
403	`EmailVerificationRequiredError`	Credentials are valid but the email address has not been verified yet. The `email` field confirms the address. Complete verification with `POST /auth/verify-email` before logging in.
404	`ProviderNotFoundError`	The specified provider is not enabled. The `provider` field confirms which one was requested.

curl --request POST \
  --url https://api.taxmaxi.com/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "local",
    "credentials": {
      "email": "[email protected]",
      "password": "kNmGP3sW_ygVLdcNVbxU"
    }
  }'

curl --request POST \
  --url https://api.taxmaxi.com/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "provider": "coinbase",
    "credentials": {
      "code": "AUTH_CODE_FROM_CALLBACK",
      "state": "STATE_FROM_AUTHORIZE"
    }
  }'

Response

{
  "token": "sess_01HXYZ...",
  "user": {
    "id": "usr_01HXYZ...",
    "email": "[email protected]",
    "displayName": "Max Mustermann"
  },
  "provider": "local",
  "expiresAt": "2026-06-14T10:00:00.000Z"
}

Store the token securely. All protected endpoints — including GET /auth/me, POST /auth/refresh, and every Sources API call — require it in the Authorization header.

​POST /auth/login

​Request body

​Response — 200 OK

​Errors

POST /auth/login

Request body

Response — 200 OK

Errors