Authentication
How authentication works across the Tiquo APIs
Authentication Overview
Tiquo uses two different authentication methods depending on which API you are calling.
Admin API: API Keys
The Admin API authenticates requests using API keys. These are organization-scoped keys that you generate from the Tiquo dashboard. Include the key as a Bearer token in the Authorization header of every request.
Authorization: Bearer your_api_key_hereAPI keys are verified through Unkey and are tied to a specific organization. Each key can only access data that belongs to its organization.
Creating API keys:
- Open your Tiquo dashboard
- Go to Settings > API
- Click Create New API Key
- Give the key a name and description
- Copy the key immediately (it will only be shown once)
Rate limits: Each API key is limited to 1,000 requests per hour. If you exceed this limit, the API responds with a 429 status code.
Client API: JWT Access Tokens
The Client API authenticates requests using JWT access tokens. These tokens are issued to individual customers through one of two authentication methods:
- DOM Package - An email OTP flow for browser-based applications
- OAuth/OIDC - A standard authorization code flow for more complex integrations
Include the JWT token as a Bearer token in the Authorization header:
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...Token details:
- Algorithm: RS256
- Issuer:
https://auth.tiquo.app - Audience:
tiquo-client-api - Access token lifetime: 1 hour
- Refresh token lifetime: 30 days
Access tokens expire after 1 hour. Use the token refresh endpoint to get a new access token before the current one expires. Refresh tokens are rotated on every use, so always store and use the new refresh token returned by the refresh endpoint.
JWT Token Claims
When a customer authenticates through either the DOM Package or OAuth, the JWT access token contains these claims:
{
"sub": "user_abc123",
"email": "customer@example.com",
"token_source": "dom",
"organization_id": "org_xyz",
"org_customer_id": "cust_456",
"customer_number": "CUST-000001",
"iss": "https://auth.tiquo.app",
"aud": "tiquo-client-api",
"exp": 1706580000,
"iat": 1706576400
}| Claim | Description |
|---|---|
sub | The user's unique ID |
email | The user's email address |
token_source | How the token was issued: dom or oauth |
organization_id | The organization the customer belongs to |
org_customer_id | The customer's ID within the organization |
customer_number | The human-readable customer number (e.g. CUST-000001) |
client_id | OAuth client ID (only present for OAuth tokens) |
scope | OAuth scopes (only present for OAuth tokens) |
Security Best Practices
- Never expose Admin API keys in client-side code, mobile apps, or public repositories
- Store API keys in environment variables or a secrets manager
- Rotate API keys periodically and revoke any that may have been compromised
- Use the Client API (with JWT tokens) for any customer-facing application
- Always validate the
token_sourceclaim if your application needs to distinguish between DOM and OAuth sessions