Authentication#

InterviewRelay uses API keys to authenticate requests. This guide covers how to obtain, use, and manage your API keys securely.

Getting Your API Key#

1. Sign in to the InterviewRelay Dashboard
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Give your key a descriptive name (e.g., "Production Server", "Staging")
5. Copy the key immediately — it will only be shown once

Using API Keys#

All API requests must include your API key in the Authorization header using the Bearer scheme.

Authorization Header Format#

Authorization: Bearer YOUR_API_KEY

JavaScript Example#

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

if (!response.ok) {
  throw new Error(`API error: ${response.status} ${response.statusText}`);
}

const data = await response.json();
console.log(data);

Python Example#

import os
import requests

API_KEY = os.environ.get('INTERVIEWRELAY_API_KEY')

response = requests.get(
    'https://api.interviewrelay.com/v1/campaigns',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json',
    }
)

response.raise_for_status()
data = response.json()
print(data)

cURL Example#

curl -X GET https://api.interviewrelay.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Key Types#

InterviewRelay uses two types of secrets:

| Key Type | Purpose | Format | Where to Find | |---|---|---|---| | Standard API Key | Authenticate API requests | ir_live_... (production) or ir_test_... (sandbox) | Settings → API Keys | | Webhook Secret | Verify incoming webhook payloads | whsec_... | Settings → Webhooks |

Standard API Key#

Used for all REST API calls. Include in the Authorization header as a Bearer token.

// Production key
const apiKey = 'ir_live_sk_abc123...';

// Test/sandbox key
const apiKey = 'ir_test_sk_xyz789...';

Webhook Secret#

Used exclusively for verifying webhook signatures. This is not sent as a header — it's used server-side to validate incoming payloads.

const crypto = require('crypto');

const WEBHOOK_SECRET = process.env.INTERVIEWRELAY_WEBHOOK_SECRET; // whsec_...

function verifyWebhookSignature(payload, signature, timestamp) {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Best Practices#

Store Keys Securely#

• Never hard-code API keys in your source code
• Never commit keys to version control (add .env to .gitignore)
• Use a secret manager in production (e.g., AWS Secrets Manager, HashiCorp Vault, Google Secret Manager)

Use Environment Variables#

# .env file (add to .gitignore!)
INTERVIEWRELAY_API_KEY=ir_live_sk_your_key_here
INTERVIEWRELAY_WEBHOOK_SECRET=whsec_your_secret_here

// Access via environment variable
const apiKey = process.env.INTERVIEWRELAY_API_KEY;

import os
api_key = os.environ.get('INTERVIEWRELAY_API_KEY')

Rotate Keys Regularly#

• Rotate API keys at least every 90 days
• Rotate immediately if a key may have been exposed
• Use the overlap period to update your services without downtime

Use Different Keys Per Environment#

Generate separate API keys for each environment:

| Environment | Key Prefix | Purpose | |---|---|---| | Development | ir_test_... | Local development and testing | | Staging | ir_test_... | Pre-production testing | | Production | ir_live_... | Live production traffic |

Key Management#

Listing Keys#

View all your API keys from Settings → API Keys. The dashboard shows:

• Key name and prefix (last 4 characters)
• Creation date
• Last used date
• Status (active / revoked)

const response = await fetch('https://api.interviewrelay.com/v1/api-keys', {
  headers: {
    'Authorization': `Bearer ${process.env.INTERVIEWRELAY_API_KEY}`,
  },
});

const { data } = await response.json();
// [{ id: "key_123", name: "Production", prefix: "ir_live_...abc", created_at: "...", last_used_at: "..." }]

Revoking Keys#

Revoke a compromised or unused key immediately:

1. Go to Settings → API Keys
2. Find the key and click Revoke
3. Confirm the action

await fetch(`https://api.interviewrelay.com/v1/api-keys/${keyId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.INTERVIEWRELAY_API_KEY}`,
  },
});

Monitoring Usage#

Track API key usage from the dashboard:

• Request count — Total requests per key over time
• Error rate — Percentage of requests returning errors
• Last used — Timestamp of the most recent request

Authentication Errors#

401 Unauthorized#

Returned when the API key is missing, invalid, or revoked.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Provide a valid key in the Authorization header.",
    "status": 401
  }
}

Common causes:

• Missing Authorization header
• Typo in the API key
• Using a revoked key
• Using a test key against the production API (or vice versa)

403 Forbidden#

Returned when the API key is valid but doesn't have permission for the requested action.

{
  "error": {
    "code": "forbidden",
    "message": "Your API key does not have permission to access this resource.",
    "status": 403
  }
}

Common causes:

• Accessing a resource that belongs to another organization
• Attempting an admin-only action with a standard key
• Exceeding rate limits

Session-based Authentication (SDK)#

When embedding interviews using the JavaScript SDK, authentication is handled via invite tokens rather than API keys. This ensures your API key is never exposed in client-side code.

// Server-side: Generate an invite token
const response = await fetch('https://api.interviewrelay.com/v1/invites', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.INTERVIEWRELAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    campaign_id: 'camp_456abc',
    participant_email: 'user@example.com',
  }),
});

const { invite_token } = await response.json();
// Pass invite_token to the client

// Client-side: Use the invite token with the SDK
InterviewRelay.mount('#interview-container', {
  inviteToken: invite_token, // From your server
});

OAuth 2.0 (Coming Soon)#

Security FAQs#

Q: Can I restrict an API key to specific IP addresses? A: IP allowlisting is available on the Enterprise plan. Contact sales for details.

Q: What happens if my API key is exposed? A: Revoke the key immediately from the dashboard and generate a new one. Review your account activity for any unauthorized actions.

Q: Are API keys encrypted at rest? A: Yes. API keys are hashed using bcrypt before storage. We never store plaintext keys.

Q: How many API keys can I create? A: You can create up to 10 API keys per account on the Free plan, 25 on Pro, and unlimited on Enterprise.

Q: Is there rate limiting? A: Yes. Default rate limits are 100 requests/minute for Free, 1,000 for Pro, and custom limits for Enterprise. See the API Reference for details.

Compliance#

InterviewRelay is built with security and compliance in mind:

GDPR#

• All data is encrypted in transit (TLS 1.3) and at rest (AES-256)
• Data residency options available (EU, US)
• Right to deletion supported via API and dashboard
• Data Processing Agreement (DPA) available on request

SOC 2#

• SOC 2 Type II certified
• Annual audits by independent third parties
• Controls for security, availability, and confidentiality

PCI DSS#

• InterviewRelay does not store, process, or transmit cardholder data directly
• Payment processing is handled by Stripe (PCI DSS Level 1 certified)

Additional Resources#

• API Reference — Full endpoint documentation
• Webhooks — Real-time event notifications
• SDK Integration — Client-side interview embedding
• Quick Start — Get started in 5 minutes