API Authentication System

This document describes the authentication system for the Shifts API, which supports two types of authentication tokens.

Authentication Types

1. User API Tokens

User API tokens are tied to a specific user and business. These tokens inherit all the permissions of the associated user, making them suitable for scenarios where you want to perform actions on behalf of a specific user. Every action performed with a user token will be attributed to the associated user.

Use cases:

• User-specific integrations
• Personal automation tools
• Integrations where user accountability is required

2. Service Account Tokens

Service account tokens provide a more secure approach for system-to-system integrations. They include both a token and a secret key, offering two-factor authentication for API access. Service account tokens are still associated with a user and business (for auditing purposes), but they can have explicitly defined permission scopes that limit their access.

Use cases:

• System-to-system integrations
• Backend services
• CI/CD pipelines
• Third-party applications

Token Security

User API Tokens

• Authenticated with a single token value
• Inherit all permissions from the associated user
• Cannot have custom permission scopes
• Visible only once when created
• Can be revoked at any time

Service Account Tokens

• Require both a token and a secret key for authentication
• Can have custom permission scopes that limit access
• Token and secret are visible only once when created
• Scopes restrict access to specific API functionality
• Can be revoked at any time

Using Tokens

User API Tokens

Include the token in the Authorization header of your requests:

Authorization: Bearer YOUR_TOKEN

Service Account Tokens

Include both the token and secret in your requests:

Authorization: Bearer YOUR_TOKEN
X-API-Secret: YOUR_SECRET

Permission Scopes

Service account tokens can be restricted to specific permission scopes:

Scope Description read:shifts View shift information write:shifts Create and modify shifts read:leave_requests View leave requests write:leave_requests Create and modify leave requests read:users View user profile information write:users Modify user information admin Full access to all API endpoints

If no scopes are specified, the token has full access (equivalent to the admin scope).

Token Management

Tokens can be managed in the administration interface:

1. Go to Admin → API → Tokens
2. Create a new user token or service account token
3. Set appropriate permissions for service account tokens
4. Copy the token (and secret for service accounts) when displayed

Important: The token and secret will only be displayed once upon creation. If you lose these values, you will need to create a new token.

Security Best Practices

1. Use service account tokens for system-to-system integrations whenever possible
2. Use the principle of least privilege by assigning only the minimum required scopes
3. Set expiration dates for all tokens when appropriate
4. Regularly audit active tokens and revoke any that are no longer needed
5. Never share tokens or secrets between different integrations or users
6. Store tokens securely using appropriate secret management solutions
7. Rotate tokens periodically (at least every 6-12 months)

Technical Implementation

The API token system is implemented with multi-tenant security in mind:

• All tokens are scoped to a specific business
• Every API request is automatically isolated to the associated business’s data
• Permission checks are enforced at multiple levels
• All API access is logged for audit purposes
• Failed authentication attempts are rate-limited