Authenticate API Requests

RiskOS™ APIs use Bearer Token authentication to secure all API requests. This guide will walk you through everything you need to authenticate successfully and troubleshoot common issues.

Retrieve your API key

1. Get your API key from the Developer Workbench > API Keys section in the RiskOS™ Dashboard.

• Access Sandbox API keys.
  • Access Production API keys.

2. Include it in your request headers:

Authorization: Bearer YOUR_API_KEY

3. Make your first request and you're ready to go!

API key management

Environment-specific keys

Each environment requires its own API key:

⚠️ Important: Never use production keys in development environments or commit keys to version control.

IP allowlists

RiskOS™ supports optional IP allowlisting to provide an extra layer of network-level security.

Allowlisting restricts access to trusted network ranges — even if valid credentials are presented.

📘 Note: IP allowlisting is an optional security control, not a requirement for API access. It defines where requests are allowed from, while your API key defines who is making the request. Both checks apply only if IP allowlisting is enabled.

How it works

1. Authentication first: Your API key is validated
2. Authorization check: Request origin IP is verified against your allowlist
3. Access granted: Only if both checks pass

Configuration

1. Go to the Developer Workbench > IP Filtering section in the RiskOS™ Dashboard.
   • Manage Sandbox IP allowlist.
   • Manage Production IP allowlist.
2. Add your trusted IP addresses or CIDR ranges.
3. Save your configuration.

Behavior

• Allowed IPs: Normal API 2xx responses
• Blocked IPs: HTTP 403 Forbidden response

Security best practices

Environment Variables

Store API keys in environment variables, never in code:

# .env file
RISKOS_SANDBOX_KEY=YOUR_SANDBOX_KEY
RISKOS_PROD_KEY=YOUR_PRODUCTION_KEY

Secure Storage

Use secure secret management:

• AWS Secrets Manager
• Azure Key Vault
• HashiCorp Vault
• Kubernetes Secrets

Monitoring

Monitor for suspicious activity:

• Unusual request patterns
• Failed authentication attempts
• Requests from unexpected IPs

Troubleshooting

Common issues

Possible causes:

• Missing Authorization header
• Incorrect API key format
• Invalid API key
• Wrong environment key (using sandbox key for production)

Solutions:

1. Verify the header format: Authorization: Bearer YOUR_API_KEY
2. Check your API key in the Developer Workbench.
3. Ensure you're using the correct environment key.

Possible causes:

• Request from non-allowlisted IP address.
• Account permissions issue.
• API endpoint access restrictions.

Solutions:

1. Check your IP allowlist configuration.
2. Verify your current IP address.
3. Contact Support if permissions seem incorrect.

Common mistakes:

// Wrong
--header 'Authorization: 'YOUR_API_KEY'  // Missing 'Bearer'

// Correct
--header 'Authorization: : 'Bearer YOUR_API_KEY'