API Authentication

Securely authenticate your API requests.

Authentication Methods

API Keys

Primary method for server-to-server integration.

Best for:

• Backend services
• Automated workflows
• Integration scripts

OAuth 2.0 (Integrations only)

OAuth is used for specific third-party integrations, not for the External REST API.

API Key Authentication

Creating an API Key

1. Go to Settings → API Keys
2. Click New API Key
3. Name your key (e.g., "CRM Integration")
4. Select permissions
5. Click Create
6. Copy the key immediately (shown only once)

Using API Keys

Include in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-domain.com/api/v1/tickets

Key Permissions

Full scope list is available in Settings → API Keys.

Revoking Keys

To revoke a compromised key:

1. Go to Settings → API Keys
2. Find the key
3. Click Revoke
4. Confirm

Note: Revoked keys stop working immediately.

OAuth for Integrations

OAuth flows are supported only for built-in integrations (e.g., Shopify, Slack). The External REST API uses API keys exclusively.

Security Best Practices

Store Keys Securely

• Never commit to version control
• Use environment variables
• Use secrets management (Vault, AWS Secrets)

Example

// Good - from environment
const apiKey = process.env.RELAY_API_KEY;

// Bad - hardcoded
const apiKey = "sk_live_abc123...";

Rotate Keys Regularly

• Generate new keys periodically
• Revoke old keys
• Update integrations

Use Least Privilege

Only request permissions you need:

• If only reading tickets, don't request write access

Monitor Usage

Review API usage:

• Check logs for unusual activity
• Set up alerts for failures
• Monitor rate limit usage

Testing Authentication

Test Your Key

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-domain.com/api/v1/tickets?limit=1

Success response:

{
  "data": []
}

Common Errors

Troubleshooting

Invalid API Key

• Check key is copied correctly
• Verify key hasn't been revoked
• Check for extra whitespace

Permission Denied

• Verify key has required scope
• Check OAuth app permissions
• Confirm resource access

Token Expired

• Refresh token if OAuth
• Generate new API key if needed

← Overview | Webhooks →