Authentication

Ring DAS APIs use Bearer token authentication with API keys. This guide shows you how to generate, manage, and use API keys to authenticate your requests.

Overview

All Ring DAS API requests require authentication via an API key passed as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Security Critical: API keys provide full access to your Ring DAS network. Never expose them in client-side code, commit them to version control, or share them publicly.

Generating API Keys

Step 1: Access API Key Management

1. Log in to your Ring DAS instance
2. Navigate to Settings > API Keys
3. Click Generate New Key

Step 2: Configure Key Settings

Provide the following information:

Step 3: Copy and Store Securely

After generation:

1. Copy the API key immediately (it will only be displayed once)
2. Store it in a secure credential management system
3. Never store API keys in:
   • Version control (Git, SVN, etc.)
   • Client-side code (JavaScript, mobile apps)
   • Unencrypted configuration files
   • Shared documents or wikis

Best Practice: Use environment variables or secrets management services (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) to store API keys.

Using API Keys in Requests

Basic Authentication Header

Include your API key in the Authorization header of every request:

GET /graphql HTTP/1.1
Host: api.ringdas.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Code Examples

# GraphQL Query Example
curl -X POST https://api.ringdas.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { network(id: \"YOUR_NETWORK_ID\") { id name status } }"
  }'

# Ad Request API Example
curl -X POST https://delivery.ringdas.com/api/v1/ads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "YOUR_NETWORK_ID",
    "adUnit": "homepage-banner",
    "count": 1
  }'

# Activity Pixel API Example
curl -X POST https://pixel.ringdas.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "YOUR_NETWORK_ID",
    "actgid": "YOUR_PIXEL_ID",
    "event": "purchased",
    "cost": "99.99",
    "ord": "ORDER-12345"
  }'

API Key Permissions

Ring DAS API keys support granular permission scopes:

Permission Levels

Module-Specific Permissions

You can restrict API keys to specific modules:

• DELIVERY: Campaign management only
• INVENTORY: Inventory configuration only
• AUDIENCE: Segment management only
• REPORTS: Reporting and analytics only
• All Modules: Full platform access

Principle of Least Privilege: Grant API keys only the minimum permissions required for their intended use case.

Rate Limiting

All authenticated requests are subject to rate limits:

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 500000
X-RateLimit-Remaining: 499850
X-RateLimit-Reset: 1704067200

Handling Rate Limit Errors

When rate limits are exceeded, you'll receive a 429 Too Many Requests response:

{
  "error": "rate_limit_exceeded",
  "message": "Daily API request limit exceeded",
  "limit": 500000,
  "reset": 1704067200
}

Best Practice: Implement exponential backoff and retry logic:

async function apiCallWithRetry(apiFunction, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    try {
      return await apiFunction();
    } catch (error) {
      if (error.response?.status === 429) {
        const resetTime = error.response.headers['x-ratelimit-reset'];
        const waitTime = Math.min(
          (resetTime - Date.now() / 1000) * 1000,
          Math.pow(2, retries) * 1000
        );

        console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        retries++;
      } else {
        throw error;
      }
    }
  }

  throw new Error('Max retries exceeded');
}

See Rate Limits & Quotas for complete details.

Security Best Practices

1. Secure Storage

DO:

• Store API keys in environment variables
• Use secrets management services (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
• Encrypt API keys at rest
• Restrict file permissions for configuration files

DON'T:

• Commit API keys to version control
• Store keys in client-side code
• Share keys via email or chat
• Log API keys in application logs

2. Key Rotation

Rotate API keys regularly:

1. Generate a new API key
2. Update applications to use the new key
3. Verify all systems are using the new key
4. Revoke the old key

Recommended Rotation Schedule: Every 90 days

3. Network Security

• Use HTTPS for all API requests (required by Ring DAS)
• Implement IP allowlisting when possible
• Use VPN or private networks for sensitive operations
• Monitor API usage for anomalies

4. Least Privilege Access

• Create separate API keys for different applications
• Grant minimum required permissions
• Use module-specific permissions when possible
• Regularly audit and revoke unused keys

5. Monitoring and Alerts

Set up monitoring for:

• Unusual API usage patterns
• Failed authentication attempts
• Rate limit warnings
• API errors and failures

Troubleshooting Authentication Issues

Invalid API Key

Error:

{
  "error": "invalid_credentials",
  "message": "Invalid or expired API key"
}

Solutions:

• Verify the API key is correct
• Check if the key has been revoked
• Ensure the key hasn't expired
• Regenerate a new key if necessary

Missing Authorization Header

Error:

{
  "error": "authentication_required",
  "message": "Missing Authorization header"
}

Solution:

// ❌ Incorrect
fetch('https://api.ringdas.com/graphql')

// ✅ Correct
fetch('https://api.ringdas.com/graphql', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
})

Insufficient Permissions

Error:

{
  "error": "insufficient_permissions",
  "message": "API key does not have permission for this operation"
}

Solutions:

• Check API key permission scope
• Request permission upgrade if needed
• Use an API key with appropriate permissions

CORS Errors (Browser)

Error:

Access to fetch at 'https://api.ringdas.com/graphql' from origin 'http://localhost:3000' has been blocked by CORS policy

Solution: Ring DAS APIs are not accessible directly from browsers due to CORS restrictions. Use a backend proxy:

// ❌ Don't call Ring DAS API directly from browser
// This exposes your API key and violates CORS policy

// ✅ Create a backend proxy
// Frontend calls your backend, backend calls Ring DAS
fetch('/api/your-backend-proxy', {
  method: 'POST',
  body: JSON.stringify({ query: '...' })
});

Testing Authentication

Verify API Key

Test your API key with a simple query:

curl -X POST https://api.ringdas.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { types { name } } }"}'

Expected Response:

{
  "data": {
    "__schema": {
      "types": [...]
    }
  }
}

Test Environment

Use a dedicated test network or staging environment:

• Avoid testing with production API keys
• Use test data for integration testing
• Request a staging environment from your account manager

API Key Management

Viewing Active Keys

Navigate to Settings > API Keys to view:

• All active API keys
• Key creation dates
• Last used timestamps
• Permission scopes

Revoking Keys

To revoke an API key:

1. Navigate to Settings > API Keys
2. Find the key to revoke
3. Click Revoke or Delete
4. Confirm the action

Warning: Revoking a key immediately disables it. Any applications using the revoked key will fail authentication.

Audit Logs

Ring DAS maintains audit logs for API key usage:

• Key generation events
• Key revocation events
• Authentication attempts
• Permission changes

Access audit logs in Settings > Audit Logs.

Next Steps

Now that you understand authentication, proceed with:

1. API Overview - Learn about available APIs
2. Campaign Operations - Create campaigns via API
3. Rate Limits & Quotas - Understand system limits
4. Error Handling - Handle API errors gracefully

Related Topics

• API Overview - Introduction to Ring DAS APIs
• Rate Limits & Quotas - System limits and monitoring
• Management API Overview - GraphQL API documentation
• SDK Overview - Client libraries and tools