Authentication

Secure your API requests with API keys

Overview

The Raily API uses API keys to authenticate requests. All API requests must include a valid API key in the Authorization header.

API Key Types

Raily provides two types of API keys:

Type	Prefix	Permissions	Use Case
Secret Key	raily_sk_	Full access	Server-side applications
Public Key	raily_pk_	Read-only	Client-side applications

Never expose your secret key in client-side code, public repositories, or browser requests. Use public keys for client-side operations.

---

Using API Keys

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

cURL

curl https://api.raily.ai/v1/content \
  -H "Authorization: Bearer raily_sk_xxxxxxxxxxxxx"

---

Managing API Keys

Create a Key

JavaScript

const key = await raily.apiKeys.create({
  name: "Production Server",
  type: "secret",
  permissions: ["content:write", "policies:write", "analytics:read"]
});

console.log(`Key created: ${key.key}`);
// Note: The full key is only shown once at creation

List Keys

const keys = await raily.apiKeys.list();

keys.data.forEach(key => {
  console.log(`${key.name}: ${key.prefix}... (${key.type})`);
  console.log(`  Created: ${key.createdAt}`);
  console.log(`  Last used: ${key.lastUsedAt}`);
});

Revoke a Key

await raily.apiKeys.revoke('key_abc123');

Rotate a Key

// Create new key, then revoke old one
const newKey = await raily.apiKeys.create({
  name: "Production Server (Rotated)",
  type: "secret",
  permissions: ["content:write", "policies:write"]
});

// Update your application with the new key
// Then revoke the old one
await raily.apiKeys.revoke('key_old123');

---

Permissions

Control what each API key can do:

Permission	Description
content:read	Read content
content:write	Create, update, delete content
policies:read	Read policies
policies:write	Create, update, delete policies
access:check	Check access permissions
analytics:read	Read analytics data
webhooks:manage	Manage webhooks
api_keys:manage	Manage API keys

Permission Examples

// Read-only analytics key
const analyticsKey = await raily.apiKeys.create({
  name: "Analytics Dashboard",
  type: "secret",
  permissions: ["analytics:read"]
});

// Content management key
const cmsKey = await raily.apiKeys.create({
  name: "CMS Integration",
  type: "secret",
  permissions: ["content:read", "content:write"]
});

// Full access key
const adminKey = await raily.apiKeys.create({
  name: "Admin",
  type: "secret",
  permissions: ["*"]  // All permissions
});

---

IP Allowlisting

Restrict API key usage to specific IP addresses:

const key = await raily.apiKeys.create({
  name: "Production Server",
  type: "secret",
  permissions: ["*"],
  allowedIps: [
    "192.168.1.100",
    "10.0.0.0/24"  // CIDR notation supported
  ]
});

---

Key Expiration

Set automatic expiration for temporary access:

const temporaryKey = await raily.apiKeys.create({
  name: "Contractor Access",
  type: "secret",
  permissions: ["content:read"],
  expiresAt: "2024-03-01T00:00:00Z"
});

---

Environment-Specific Keys

Best practice: Use different keys for each environment:

// .env.development
RAILY_API_KEY=raily_sk_dev_xxxxx

// .env.staging
RAILY_API_KEY=raily_sk_staging_xxxxx

// .env.production
RAILY_API_KEY=raily_sk_prod_xxxxx

---

Security Best Practices

Use Environment Variables

Never hardcode API keys. Use environment variables or secrets managers.

Rotate Regularly

Rotate keys periodically and immediately if compromised.

Least Privilege

Give each key only the permissions it needs.

Monitor Usage

Review key usage in the dashboard to detect anomalies.

Example: Using AWS Secrets Manager

import { SecretsManager } from '@aws-sdk/client-secrets-manager';

const secretsManager = new SecretsManager({ region: 'us-east-1' });

async function getRailyClient() {
  const secret = await secretsManager.getSecretValue({
    SecretId: 'raily/api-key'
  });

  return new Raily({
    apiKey: JSON.parse(secret.SecretString).apiKey
  });
}

Example: Using HashiCorp Vault

import vault from 'node-vault';

const client = vault({ endpoint: 'https://vault.example.com' });

async function getRailyClient() {
  const { data } = await client.read('secret/data/raily');

  return new Raily({
    apiKey: data.data.apiKey
  });
}

---

Error Responses

Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked",
    "type": "authentication_error"
  }
}

Missing API Key

{
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided. Include your key in the Authorization header.",
    "type": "authentication_error"
  }
}

Insufficient Permissions

{
  "error": {
    "code": "insufficient_permissions",
    "message": "This API key does not have permission to access this resource",
    "type": "authorization_error"
  }
}

IP Not Allowed

{
  "error": {
    "code": "ip_not_allowed",
    "message": "Request from IP 203.0.113.50 is not allowed for this API key",
    "type": "authorization_error"
  }
}

---

Next Steps

Content API

Start managing content

SDKs

Use our official SDKs