API Configuration and Token Management

Learn how to create and manage API tokens, configure API access limits, monitor usage, and enable secure programmatic access to your organization’s data in the Shifts platform.

Overview

The API Configuration features in Shifts allow administrators to create and manage secure API tokens for programmatic access to the platform. These tokens enable integration with third-party systems, custom applications, and business intelligence tools while maintaining security and controlling access to your organization’s data.

Understanding API Access

What is the Shifts API?

The Shifts API (Application Programming Interface) allows external systems to:

• Retrieve data from the Shifts platform (e.g., schedules, employee information)
• Create or update records (e.g., create shifts, update employee information)
• Perform actions (e.g., generate reports, send notifications)

Authentication Methods

The Shifts platform uses token-based authentication:

• API tokens are secure credentials that identify and authorize API requests
• Each token has specific permissions and usage limits
• Tokens can be created, monitored, and revoked as needed

Creating API Tokens

Token Generation Process

To create a new API token:

1. Navigate to Admin Dashboard → System Configuration → API Settings
2. Click the API Tokens tab
3. Click Generate New Token
4. Enter the following details:
   • Token Name: A descriptive name (e.g., “Payroll Integration”)
   • Associated User: The user account the token will operate under
   • Permission Scope: Select which API endpoints the token can access
   • Expiration Date (Optional): Set a date when the token will automatically expire
5. Click Generate Token
6. Copy the displayed token immediately - for security reasons, it can’t be viewed again

Permission Scopes

When creating tokens, you can limit access to specific areas:

• Read-Only: Can only retrieve data, not modify it
• Full Access: Can read and write data within its permission scope
• Limited: Access to specific endpoints only (e.g., shifts, attendance)

Each scope can be further restricted to specific business units, locations, or user groups.

Managing API Tokens

Viewing Existing Tokens

To see all tokens for your organization:

1. Go to Admin Dashboard → System Configuration → API Settings → API Tokens
2. The list shows all active tokens with:
   • Token name
   • Creation date
   • Last used date
   • Associated user
   • Status (active/inactive)
   • Expiration date (if set)

Revoking Tokens

If a token needs to be disabled:

1. Find the token in the list
2. Click the Revoke button
3. Confirm the revocation
4. The token will immediately become invalid for all API calls

Monitoring Token Usage

To track how tokens are being used:

1. Go to Admin Dashboard → System Configuration → API Settings → Usage Analytics
2. Select a token from the dropdown
3. View usage statistics:
   • Request volume over time
   • Endpoints accessed
   • Success/failure rates
   • Average response times

API Rate Limiting

Setting Usage Limits

To prevent abuse and ensure system stability:

1. Go to Admin Dashboard → System Configuration → API Settings → Rate Limits
2. Configure global limits:
   • Requests per Hour: Maximum number of API calls allowed per hour
   • Burst Rate: Maximum requests allowed in a short time period
3. Configure token-specific limits:
   • Select a token from the list
   • Set custom rate limits for this token
   • Save your changes

Understanding Rate Limit Headers

API responses include rate limit information:

• X-RateLimit-Limit: The maximum number of requests allowed per hour
• X-RateLimit-Remaining: The number of requests remaining in the current window
• X-RateLimit-Reset: The time when the rate limit window resets (Unix timestamp)

Security Best Practices

API Token Security

To maintain secure API access:

1. Treat tokens like passwords - store them securely
2. Use expiration dates for temporary integrations
3. Limit permissions to only what’s needed
4. Regularly audit token usage and revoke unused tokens
5. Rotate tokens periodically for critical integrations
6. Never share tokens in public repositories or insecure channels

IP Restrictions

For additional security, limit API access to specific IP addresses:

1. Go to Admin Dashboard → System Configuration → API Settings → IP Restrictions
2. Click Add IP Range
3. Enter the IP address or CIDR range that should have access
4. Apply restrictions to specific tokens or all API access
5. Save your changes

Troubleshooting API Issues

Common API Errors

If you’re experiencing API problems:

1. 401 Unauthorized: Token is invalid or has been revoked
2. 403 Forbidden: Token lacks permission for the requested operation
3. 429 Too Many Requests: Rate limit has been exceeded
4. 404 Not Found: Endpoint doesn’t exist or resource wasn’t found
5. 400 Bad Request: Request format is incorrect

API Logs

For debugging integration issues:

1. Go to Admin Dashboard → System Configuration → API Settings → API Logs
2. Filter logs by:
   • Date range
   • Token
   • Endpoint
   • Status code
3. View detailed request and response information
4. Export logs for further analysis

Related Resources

• System Settings
• Security Settings
• Custom API Development
• API Usage Monitoring

This article should be updated when:

1. The API token generation process changes
2. New permission scopes are added
3. Rate limiting algorithms or defaults are modified
4. API security features are enhanced
5. New API monitoring or logging features are introduced