Authentication

All API requests require authentication using an API key passed as a Bearer token.

Getting an API Key

To use the API, you need to generate an API key from your workspace settings:

1. Sign in to your Agents for Data account
2. Navigate to Settings → API Keys
3. Click "Create API Key"
4. Provide a name for your key (e.g., "Production API")
5. Select the permissions your key needs
6. Copy the key immediately - it will only be shown once

Using Your API Key

Include your API key in the Authorization header of every request as a Bearer token:

curl https://agentsfordata.com/api/public/v1/convert/formats \
  -H "Authorization: Bearer tablab_api_xxxxxxxxxxxxx"

API Key Format

API keys follow this format:

tablab_api_[40 random characters]

Example: tablab_api_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r

API Key Permissions

When creating an API key, you can grant it specific permissions:

Additional permissions will be added as more API endpoints become available.

Managing API Keys

Viewing Your Keys

You can view all your API keys in the API Keys settings page. Each key shows:

• Key name and prefix (first 20 characters)
• Creation date
• Last used date
• Expiration date (if set)
• Permissions

Rotating Keys

To rotate an API key:

1. Create a new API key with the same permissions
2. Update your applications to use the new key
3. Test that the new key works correctly
4. Delete the old key

Revoking Keys

If a key is compromised or no longer needed:

1. Go to Settings → API Keys
2. Find the key you want to revoke
3. Click "Delete"
4. Confirm deletion

Revoked keys stop working immediately. Any requests using the revoked key will receive a 401 Unauthorized error.

Security Best Practices

Never Expose Keys

• Don't commit API keys to version control (Git, SVN, etc.)
• Don't include keys in client-side JavaScript
• Don't share keys in screenshots, logs, or error messages
• Don't post keys in public forums or support tickets

Use Environment Variables

Store API keys in environment variables, not in your code:

# .env file (don't commit this!)
AGENTS_API_KEY=tablab_api_xxxxxxxxxxxxx

// In your code
const apiKey = process.env.AGENTS_API_KEY;

Limit Permissions

Create separate API keys for different applications or environments:

• Development: Key with limited permissions for testing
• Production: Key with only the permissions needed
• CI/CD: Separate key for automated deployments

Rotate Regularly

Rotate your API keys periodically (every 90 days recommended):

• Reduces risk of compromised keys
• Limits exposure if a key is leaked
• Good security hygiene

Monitor Usage

Regularly check your API key usage:

• Review "Last Used" dates for each key
• Delete keys that haven't been used recently
• Monitor for unexpected usage patterns

Authentication Errors

401 Unauthorized

This error means your API key is invalid or missing:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Common causes:

• API key not included in the Authorization header
• API key format is incorrect (missing "Bearer " prefix)
• API key has been revoked or deleted
• API key has expired

403 Forbidden

This error means your API key doesn't have permission for the requested operation:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API key lacks required permissions"
  }
}

Solution:

• Check which permissions your API key has
• Create a new key with the required permissions
• Update your application to use the new key

Testing Authentication

Test your API key by listing available formats:

curl https://agentsfordata.com/api/public/v1/convert/formats \
  -H "Authorization: Bearer YOUR_API_KEY"

If successful, you'll receive a list of supported file formats. If not, check the error message for details.