How to Use API Keys

What This Feature Does

API keys provide secure, programmatic access to the Assignar Pay API. They allow you to integrate Assignar Pay with your existing systems, build custom applications, and automate workflows. Each API key has configurable permissions (scopes) and optional expiration dates for enhanced security.

Initial Setup

Accessing API Keys Management

1. Navigate to your account settings by clicking your account name in the top right corner
2. Select "Settings" from the dropdown menu
3. Click on the "API Keys" tab in the settings page

Required Permissions

Before creating API keys, ensure you have:

• Account owner or administrator permissions
• Access to the account settings page
• Understanding of what data your integration needs to access

Day-to-Day Usage

How to Create an API Key

1. Go to Settings > API Keys tab

2. Scroll to the "Create API Key" section at the top of the page

3. Enter a descriptive name for your API key (e.g., "Production Integration", "Reporting Script", "Mobile App")

4. Configure expiration settings:

   • Never expires: For long-term integrations (recommended for production)
   • Preset duration: Choose 1 day, 7 days, 30 days, or 90 days
   • Custom date: Select a specific expiration date

5. Configure permissions (scopes):

   • Click "Add Scope" to add additional permissions
   • Select the Entity Type (e.g., "payroll")
   • Select the Action (read, create, update, delete, or * for all actions)
   • Remove scopes you don't need by clicking the trash icon

6. Click "Create API Key" button

7. Important: Copy your API key immediately - you won't be able to see it again!

How to Use Your API Key

Once you have your API key, include it in API requests using one of these methods:

Method 1: X-API-KEY Header (Recommended)

curl -X GET "https://pay.assignar.com/api/v1/pay-rates" \
  -H "X-API-KEY: sk_your_api_key_here"

Method 2: Authorization Bearer Header

curl -X GET "https://pay.assignar.com/api/v1/pay-rates" \
  -H "Authorization: Bearer sk_your_api_key_here"

JavaScript/TypeScript Example

const response = await fetch('https://pay.assignar.com/api/v1/pay-rates', {
  headers: {
    'X-API-KEY': 'sk_your_api_key_here',
    'Content-Type': 'application/json',
  },
});

Python Example

import requests

headers = {
    'X-API-KEY': 'sk_your_api_key_here',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://pay.assignar.com/api/v1/pay-rates',
    headers=headers
)

How to View Your API Keys

1. Go to Settings > API Keys tab
2. Scroll to the "API Keys" section below the create form
3. View all your API keys in a table showing:
   • Name: The descriptive name you gave the key
   • Key Prefix: First few characters of the key (for identification)
   • Scopes: What permissions the key has
   • Created: When the key was created
   • Last Used: When the key was last used (if ever)
   • Expires: Expiration date or "Never"
   • Status: Active, Expired, or Revoked

How to Revoke an API Key

1. Go to Settings > API Keys tab
2. Find the API key you want to revoke in the list
3. Click the trash icon in the "Actions" column
4. Confirm the revocation in the dialog that appears

Warning: Revoking an API key immediately stops it from working. Any applications using this key will lose access.

Common Tasks

Setting Up Different Keys for Different Environments

1. Create separate API keys for development, staging, and production
2. Use descriptive names like:
   • "Development - Local Testing"
   • "Staging - Integration Testing"
   • "Production - Live System"
3. Set shorter expiration dates for development keys
4. Use more restrictive scopes for development keys

Creating Keys with Limited Permissions

1. When creating a key, only add the scopes you need
2. For read-only integrations, only add "read" actions
3. For write operations, add specific "create", "update", or "delete" actions
4. Avoid using "*" (all actions) unless absolutely necessary

Managing Key Expiration

1. For production integrations, set keys to "Never expires" or long durations (90 days)
2. For temporary scripts or testing, use shorter durations (1-7 days)
3. Monitor expiration dates in the API keys list
4. Keys expiring within 7 days show a warning icon
5. Create replacement keys before expiration to avoid service interruption

Rotating API Keys for Security

1. Create a new API key with the same scopes
2. Update your application to use the new key
3. Test that everything works with the new key
4. Revoke the old key once the new one is confirmed working
5. Repeat this process regularly (e.g., every 90 days)

Advanced API Key Management

Understanding Scopes

Scopes define what your API key can access:

• Entity Type: The type of resource (e.g., "payroll")
• Action: What operations are allowed:
  • read: View data only
  • create: Create new records
  • update: Modify existing records
  • delete: Remove records
  • *: All actions

API Key Limits

• Maximum of 3 active API keys per account
• If you reach the limit, revoke an unused key before creating a new one
• Expired or revoked keys don't count toward the limit

Key Status Indicators

• Green border: Active key that hasn't expired
• Yellow border: Key that has expired but hasn't been revoked
• Red border: Key that has been revoked
• Warning icon: Key expiring within 7 days

Troubleshooting

If your API key isn't working

• Verify the key is copied correctly (no extra spaces or characters)
• Check that the key status is "Active" in the API keys list
• Ensure the key hasn't expired
• Verify you're using the correct header format (X-API-KEY or Authorization: Bearer)
• Check that your scopes include the required permissions for the endpoint

If you can't create a new API key

• Check if you've reached the limit of 3 active keys
• Revoke an unused or expired key to free up a slot
• Verify you have permission to create API keys (account owner/admin)

If you lost your API key

• API keys are only shown once when created
• If you didn't copy it, you'll need to create a new key
• Revoke the old key if you suspect it was compromised
• Consider rotating all keys if security is a concern

If an API key expired unexpectedly

• Check the expiration date in the API keys list
• Create a new key with a longer expiration or "Never expires"
• Update your application to use the new key
• Revoke the expired key once migration is complete

Tips for Secure API Key Usage

• Never commit API keys to version control - Use environment variables instead
• Use different keys for different applications - Makes it easier to revoke access if needed
• Set expiration dates - Even for production keys, consider setting expiration dates
• Monitor last used dates - Revoke keys that haven't been used in a while
• Use minimal scopes - Only grant the permissions you actually need
• Rotate keys regularly - Change keys periodically for better security
• Store keys securely - Use secure storage solutions, not plain text files

Best Practices for API Key Setup

Naming Conventions

• Use clear, descriptive names that indicate the key's purpose
• Include environment information (dev, staging, prod)
• Include the application or service name
• Examples: "Production - Reporting Dashboard", "Staging - Mobile App", "Development - Testing Script"

Scope Management

• Start with minimal permissions and add more as needed
• Use separate keys for different applications or services
• Review and audit scopes regularly
• Remove unused scopes to reduce security risk

Expiration Strategy

• Production keys: Long expiration (90 days) or never expires
• Staging keys: Medium expiration (30 days)
• Development keys: Short expiration (1-7 days)
• Temporary scripts: Custom date matching project timeline

What's Next

After setting up API keys, you may want to:

• Explore the API Documentation to see available endpoints
• Review example API requests and responses
• Set up monitoring for API key usage
• Configure your application to handle API errors gracefully