BillClap uses API tokens for server-to-server authentication. Tokens are generated only from the BillClap application—not via a public API endpoint.

​
Generate your token

  1. Log in to app.billclap.com
  2. Select your business
  3. Go to Settings → API Integration
  4. Generate and copy your API token
Tokens can only be generated once per business. Store the token in a secrets manager or environment variable—never in client-side code.
Every API request must include: 
x-api-token: <your-api-token>
Do not use Authorization: Bearer for API integration endpoints. The dedicated header is x-api-token.

​
Token lifecycle

PropertyValue
GenerationOnce per business, from BillClap Settings
Validity365 days from generation
ScopeTied to user_id + business_id
Plan requirementAPI integration feature must be enabled

​
How tokens are structured

When you generate a token in the BillClap app, the backend:
  1. Creates a JWT payload with user_id, business_id, and type: "api_token"
  2. Signs it with API_TOKEN_SECRET
  3. Wraps it in an outer encrypted JWT signed with API_ENCRYPTION_SECRET
  4. Stores the encrypted token on the business record
When you call an API endpoint, the server:
  1. Verifies the outer JWT using API_ENCRYPTION_SECRET
  2. Verifies the inner JWT using API_TOKEN_SECRET
  3. Confirms type === "api_token"
  4. Attaches user_id and business_id to the request context

​
Error responses

HTTP StatusMessageCause
401API token is requiredMissing x-api-token header
401Invalid token typeToken is not an API token
401JWT error messageExpired, invalid, or tampered token
200Plan permission errorBusiness plan does not include API integration

​
Security best practices

  • Store tokens in environment variables or a secrets manager — never in client-side code
  • Rotate by contacting support if a token is compromised (regeneration is one-time only today)
  • Use HTTPS for all requests
  • Restrict token access to backend services only