API Authentication

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_here

Each API key is tied to a specific organization and a set of permissions. Tiquo validates the key on every request and limits it to data and operations allowed for that organization.

Creating API keys:

1. Open your Tiquo dashboard
2. Go to Settings > Admin API
3. Click Create New API Key
4. Give the key a name and description
5. Select only the read and write permissions the integration needs
6. Optionally restrict the key to specific web origins or IP addresses
7. Copy the key immediately (it will only be shown once)

Rate limits: The default limit is 1,000 requests per API key in a fixed one-hour window. If you exceed the limit, the API responds with a 429 status code until the current window resets. Contact Tiquo if your integration needs a higher rate limit; rate limits cannot be changed from the dashboard.

Customer API: JWT Access Tokens

The Customer 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: up to 1 hour
• Refresh token lifetime: until the original customer session expires; Auth DOM defaults to 30 days but the organization can configure another duration

Access tokens expire after at most 1 hour and can be shorter when the customer session is close to expiry. 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
}

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
• Grant each key the minimum permissions it needs and use origin or IP restrictions where appropriate
• Rotate API keys periodically and revoke any that may have been compromised
• Use the Customer API (with JWT tokens) for any customer-facing application
• Always validate the token_source claim if your application needs to distinguish between DOM and OAuth sessions