Authentication

AI Interview uses API keys to authenticate requests. All API requests must include your API key in the Authorization header.

Getting Your API Key

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Give it a descriptive name (e.g., "Production API")
4. Copy the key (shown only once!)
5. Store it securely

Using API Keys

Authorization Header

Include your API key in the Authorization header with Bearer authentication:

curl https://api.interviewrelay.com/api/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY"

###JavaScript Example

const API_KEY = process.env.INTERVIEWRELAY_API_KEY;

const response = await fetch('https://api.interviewrelay.com/api/campaigns', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

Python Example

import os
import requests

API_KEY = os.environ['INTERVIEWRELAY_API_KEY']

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://api.interviewrelay.com/api/campaigns',
    headers=headers
)

data = response.json()

API Key Types

Standard API Keys

For server-to-server authentication:

• Full access to your account's resources
• No expiration (unless manually revoked)
• Can be scoped to specific permissions (coming soon)

Webhook Secrets

For verifying webhook signatures:

• Created automatically when you set up a webhook
• Used to verify webhook authenticity
• See Webhooks for details

Best Practices

Store Keys Securely

✅ Do:

• Use environment variables
• Use a secrets manager (AWS Secrets Manager, HashiCorp Vault)
• Encrypt at rest in your database

❌ Don't:

• Commit to version control
• Include in client-side code
• Share via email or chat

Environment Variables

# .env (gitignored!)
INTERVIEWRELAY_API_KEY=sk_live_abc123...
WEBHOOK_SECRET=whsec_xyz789...

// Load from environment
require('dotenv').config();

const apiKey = process.env.INTERVIEWRELAY_API_KEY;

Rotate Keys Regularly

Rotate API keys every 90 days or immediately if compromised:

1. Create a new API key
2. Update your application configuration
3. Test to ensure it works
4. Revoke the old key

Use Different Keys per Environment

Create separate API keys for:

• Development: sk_dev_...
• Staging: sk_staging_...
• Production: sk_live_...

This allows you to revoke keys without affecting all environments.

Key Management

Listing API Keys

View all your API keys in Settings → API Keys:

• Key name
• Created date
• Last used date
• Key prefix (e.g., sk_live_abc...)

Revoking Keys

Immediately revoke compromised keys:

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

Revoked keys become invalid immediately. All API requests using the revoked key will return 401 Unauthorized.

Monitoring Usage

Track API key usage:

• Last Used: When the key was last used
• Request Count: Total requests made with this key
• Failed Attempts: Failed authentication attempts

Authentication Errors

401 Unauthorized

Cause: Invalid or missing API key

Response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Solution:

• Verify your API key is correct
• Check that the key hasn't been revoked
• Ensure you're using the correct key for the environment

403 Forbidden

Cause: Valid API key but insufficient permissions

Response:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this resource"
  }
}

Solution:

• Check that your account has access to the resource
• Verify you're using the correct project/campaign ID
• Ensure your plan includes the requested feature

Session-based Authentication (SDK)

The embeddable SDK uses invite tokens instead of API keys:

InterviewSDK.mount('#container', {
  invite: 'inv_8f7d9e2c1a0b3h4k5j6m', // Invite token, not API key
});

Invite tokens are:

• Single-use only
• Time-limited (configurable expiry)
• Scoped to a specific interview session
• Safe to expose in client-side code

See SDK Integration for details.

OAuth 2.0 (Coming Soon)

We're working on OAuth 2.0 support for third-party integrations. This will allow:

• User-authorized access without sharing API keys
• Fine-grained permission scopes
• Token refresh and expiration

Stay tuned for updates!

Security FAQs

Can I use API keys in frontend JavaScript?

No. API keys grant full access to your account and should only be used server-side. For client-side embeds, use invite tokens.

What if my API key is leaked?

1. Immediately revoke the key in Settings → API Keys
2. Create a new key and update your applications
3. Monitor your account for unauthorized activity
4. Review access logs for suspicious requests
5. Contact support if you notice unauthorized usage

How long are API keys valid?

API keys don't expire automatically. However, we recommend rotating them every 90 days as a security best practice.

Can I restrict API keys by IP address?

Not yet, but this feature is on our roadmap. For now, use separate keys per environment and rotate regularly.

Are API requests logged?

Yes. We log:

• API endpoint accessed
• Timestamp
• Response status code
• API key used (hashed)

We do not log request/response bodies or full API keys.

Compliance

GDPR

API keys are considered security credentials and are not subject to data subject access requests (DSARs).

SOC 2

We follow SOC 2 Type II compliance for API key storage and management:

• Keys are hashed using bcrypt before storage
• Access logs are retained for 90 days
• Failed authentication attempts are rate-limited

PCI DSS

API keys are stored separately from payment information and never co-mingled with cardholder data.

Additional Resources

• API Reference - Complete API documentation
• SDK Integration - Client-side integration
• Webhooks - Real-time event notifications
• Security Best Practices - OWASP API Security

Support

Security concerns or questions?

• Security Issues: support@interviewrelay.com
• General Support: support@interviewrelay.com
• Documentation: Visit docs.interviewrelay.com