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](https://riskos.sandbox.socure.com/developers/api-keys).
   - [Access Production API keys](https://riskos.socure.com/developers/api-keys).

2. Include it in your request headers:

```http
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:

| 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

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](https://riskos.sandbox.socure.com/developers/ip-filtering).
   - [Manage Production IP allowlist](https://riskos.socure.com/developers/ip-filtering).
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:

```shell
# .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](mailto:support@socure.com) if permissions seem incorrect.

### Common mistakes:

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

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