Authentication

Overview

SynthesQ API uses Bearer token authentication to secure all endpoints. Every API request must include a valid authentication token in the request headers.

Authentication Flow

1. Obtain Access Token

To access the API, you first need to obtain an access token through the authentication endpoint. This typically involves:

1. Providing valid credentials (email/password or API key)
2. Receiving an access token in the response
3. Storing the token securely for subsequent requests

Token Characteristics:

• Tokens have an expiration time (check your organization's policy)
• Tokens are tenant-specific (access only your organization's data)
• Tokens can be revoked by administrators

2. Include Token in Requests

For every API request, include your access token in the Authorization header using the Bearer authentication scheme.

Header Format:

Authorization: Bearer {your-access-token}

The token must be included in every request to protected endpoints.

3. Handle Token Expiration

When a token expires, you will receive a 401 Unauthorized response. Your application should:

1. Detect the 401 status code
2. Prompt for re-authentication
3. Obtain a new token
4. Retry the original request with the new token

Multi-Tenancy Considerations

SynthesQ is a multi-tenant system where each organization has isolated data:

• Tenant Identification: Your access token automatically identifies your tenant
• Data Isolation: You can only access data belonging to your organization
• No Manual Tenant Selection: Tenant context is automatically applied based on your token
• Superuser Onboarding: New tenant administrators are invited via secure email invitation flow (see Tenant Management guide)

Security Best Practices

Token Storage

• Never store tokens in client-side code or version control
• Use secure storage mechanisms (encrypted databases, secure vaults)
• Clear tokens on logout

Token Transmission

• Always use HTTPS for API requests
• Never pass tokens in URL query parameters
• Avoid logging tokens in application logs

Token Lifecycle

• Implement automatic token refresh before expiration
• Handle graceful degradation when tokens expire
• Provide clear error messages to users

Common Authentication Scenarios

Web Applications

Web applications typically:

1. Store tokens in secure HTTP-only cookies
2. Implement automatic token refresh
3. Clear tokens on user logout

Mobile Applications

Mobile apps should:

1. Store tokens in secure device storage (Keychain/KeyStore)
2. Refresh tokens in background
3. Handle token expiration gracefully

Server-to-Server Integration

For API integrations:

1. Use long-lived API keys instead of user credentials
2. Rotate API keys periodically
3. Monitor API key usage for suspicious activity

Authentication Errors

401 Unauthorized

Meaning: Token is missing, invalid, or expired

Resolution:

• Verify token is included in Authorization header
• Check token format (must be: Bearer {token})
• Obtain a new token if expired

403 Forbidden

Meaning: Token is valid but lacks required permissions

Resolution:

• Verify your user role has access to the endpoint
• Contact your administrator to request necessary permissions
• Check tenant-specific access controls

Testing Authentication

When testing API endpoints:

1. Development Environment: Use development tokens with longer expiration
2. Testing Tools: Configure authentication in your HTTP client (Postman, Insomnia)
3. Automated Tests: Use test-specific tokens with appropriate scopes

Authentication Flows

Standard User Login

Regular users authenticate using email and password:

1. User provides credentials (email/password)
2. Server validates credentials and returns access token
3. User includes token in subsequent requests

Superuser Invitation Flow

New tenant superusers are onboarded through a secure invitation flow:

1. Landlord admin creates superuser with email only (no password)
2. User receives secure invitation email
3. User clicks invitation link to frontend
4. User creates their own password
5. User can then login with email and password

See Tenant Management Guide for complete details on the superuser invitation flow.

Related Resources

• Tenant Management - Landlord tenant management and superuser invitations
• API Reference - View authentication requirements for each endpoint
• Error Handling - Understanding authentication error responses