> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate your API requests with an API key, and confirm that each webhook really came from Baselayer.

Baselayer uses **API key authentication** for API requests and **HMAC-SHA256 signatures** for webhook verification. This guide covers both authentication methods.

***

## API Authentication

All Baselayer API requests require authentication using an API key passed in the `X-API-Key` header.

### Getting Your API Key

1. Log into the [Baselayer console](https://console.baselayer.com)
2. Select your environment using the dropdown in the top-left corner (SANDBOX or PRODUCTION). If your organization has KYA, this control is a switch just above your name at the bottom of the sidebar instead.
3. Click your name at the bottom of the sidebar, then **API Keys**
4. Copy your API key

**⚠️ Important**: Make sure you've selected the correct environment before copying your key. Sandbox keys only work with sandbox data, and production keys will incur charges. See [Sandbox vs. Production Environments](https://docs.baselayer.com/docs/sandbox-vs-production-environments.md) for details.

### Base URL

All API requests use the same base URL:

```
https://api.baselayer.com
```

### Making Authenticated Requests

Include your API key in the `X-API-Key` header with every request.

#### cURL Example

```bash theme={null}
curl https://api.baselayer.com/searches \
  -X POST \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Baselayer Technologies Inc",
    "address": "149 New Montgomery St, San Francisco, CA 94105"
  }'
```

#### Python Example

Using the `requests` library:

```python theme={null}
import requests

url = "https://api.baselayer.com/searches"

headers = {
    "X-API-Key": "your_api_key_here",
    "Content-Type": "application/json"
}

payload = {
    "name": "Baselayer Technologies Inc",
    "address": "149 New Montgomery St, San Francisco, CA 94105"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
```

***

## Webhook Authentication

Baselayer uses Svix to deliver webhooks with HMAC-SHA256 signatures for secure verification.

### How Webhook Signing Works

Every webhook request includes cryptographic signatures in the headers that you can verify to ensure:

* The webhook came from Baselayer (not a malicious third party)
* The payload hasn't been tampered with

### Getting Your Signing Secret

1. Log into the [Baselayer console](https://console.baselayer.com)
2. Click your name at the bottom of the sidebar, then **Webhooks & Logs**
3. Find your webhook endpoint
4. The signing secret is displayed next to your endpoint URL

The secret will look like: `whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD`

![](https://mintcdn.com/baselayer-81245324/y8jjNyo-CIhfj2Df/images/Screenshot_2025-12-29_at_16.46.45.png?fit=max\&auto=format\&n=y8jjNyo-CIhfj2Df\&q=85\&s=1a81e060812c8275e5b4710778a9370b)

### Verifying Webhook Signatures

Baselayer uses Svix for webhook delivery. For detailed verification instructions and code examples, see the [Svix webhook verification guide](https://docs.svix.com/receiving/verifying-payloads/how-manual).

***

## Security Best Practices

### Protecting Your API Keys

**✓ Use environment variables**: Never hardcode API keys in your code

```python theme={null}
import os
api_key = os.environ.get("BASELAYER_API_KEY")
```

**✓ Use secret managers**: For production, use AWS Secrets Manager, Google Secret Manager, or similar

**✓ Never commit keys to version control**: Add `.env` files to your `.gitignore`

```bash theme={null}
# .gitignore
.env
*.env
```

**✗ Don't expose keys in client-side code**: API keys should only be used in backend services

### Environment Separation

* **Development/Testing**: Use sandbox API keys
* **Production**: Use production API keys only in your live application

Accidentally using production keys during testing will result in unexpected charges.

### Key Rotation

If you believe an API key has been compromised:

1. Generate a new API key in the Baselayer console
2. Update your application to use the new key
3. Delete the compromised key
4. Monitor your usage for any suspicious activity

### Webhook Security

* **Always verify signatures**: Check the HMAC signature on every webhook
* **Use HTTPS endpoints**: Webhook endpoints must use HTTPS
* **Implement idempotency**: Webhooks may be delivered more than once; use the event ID to deduplicate

***

## Troubleshooting

### 401 Unauthorized

**Cause**: Missing or invalid API key

**Solutions**:

* Verify the `X-API-Key` header is included in your request
* Check that you copied the complete API key (no extra spaces or characters)
* Confirm you're using a valid, non-deleted API key
* Ensure you're using the correct environment key (sandbox vs. production)

### 403 Forbidden

**Cause**: Your API key doesn't have access to the requested resource

**Solutions**:

* Verify you're using a production key for production resources
* Check that your account has access to the endpoint you're calling

***

## Next Steps

Now that you understand authentication, you're ready to:

* [Understand Sandbox vs. Production environments](https://docs.baselayer.com/docs/sandbox-vs-production-environments.md)
* [Set up webhooks](https://docs.baselayer.com/docs/webhooks-at-baselayer.md)
* [Get started with the Baselayer API](https://docs.baselayer.com/docs/getting-started.md)

For questions about authentication or API access, contact your Baselayer account manager.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.