Skip to main content
The TaxHomeBase API uses AWS Cognito for authentication. Every API request (except health check and Stripe webhook) must include a valid JWT access token.

​
Authorization Header

Include the token in the Authorization header: 
curl -H "Authorization: Bearer eyJraWQiOiJ..." \
  https://app.taxhomebase.com/api/v1/me

​
Obtaining a Token

Tokens are obtained through the AWS Cognito authentication flow:
  1. Sign up — Create an account with email and password via the Cognito Hosted UI or SDK
  2. Sign in — Authenticate to receive an access token, ID token, and refresh token
  3. Use the access token — Pass it in the Authorization header for API requests
  4. Refresh — When the access token expires, use the refresh token to get a new one
The web application handles this flow automatically. If you’re building a custom integration, use the AWS Amplify SDK or the Cognito Identity SDK.

​
Token Lifecycle

TokenLifetimePurpose
Access Token1 hourAPI authentication
ID Token1 hourUser identity claims
Refresh Token30 daysObtain new access/ID tokens

​
Authentication Errors

StatusMeaning
401 UnauthorizedToken is missing, expired, or invalid
403 ForbiddenToken is valid but user lacks permission (wrong plan, disabled account, not admin)

​
401 Response

{
  "error": "Authentication required"
}

​
403 Response (Plan Gate)

{
  "error": "Pro plan required"
}

​
403 Response (Disabled Account)

{
  "error": "Account is disabled"
}

​
Middleware Chain

The API applies middleware in this order:
  1. requireAuth — Validates the JWT, extracts user identity, creates user record on first login
  2. requirePlan(‘pro’) — (Pro-gated endpoints only) Checks the user’s subscription plan
  3. requireAdmin — (Admin endpoints only) Checks the is_admin flag
  4. activityLogger — Logs the request to the activity_logs table