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

Get your API key from the Developer Workbench > API Keys section in the RiskOS™ Dashboard.
- Access Sandbox API keys.
- Access Production API keys.

Include it in your request headers:

Authorization: Bearer YOUR_API_KEY

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

API key management

Environment-specific keys

Each environment requires its own API key:

Environment	Description	Endpoint URL
Sandbox	For development and testing	`https://riskos.sandbox.socure.com/api/evaluation`
Production	For live applications	`https://riskos.socure.com/api/evaluation`

⚠️
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

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

Configuration

Go to the Developer Workbench > IP Filterings section in the RiskOS™ Dashboard.
- Manage Sandbox IP allowlist.
- Manage Production IP allowlist.
Add your trusted IP addresses or CIDR ranges.
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

401 Unauthorized

Possible causes:

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

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

403 Forbidden

Possible causes:

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

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

Header Not Sent

Common mistakes:

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

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