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

# API Authentication

> Learn how to authenticate with the deepidv API

> deepidv uses API keys to authenticate every request. Pass your secret key via HTTP header — missing or invalid keys return a 401 error.

## Finding Your API Key

In deepidv, API keys are scoped to your **Organization**. Your organization is the workspace where your team manages workflows, verification sessions, and billing.

An API key is generated when you first create your organization. To find or regenerate your key:

<Steps>
  <Step title="Log in to the Admin Console">
    Go to the [**deepidv Admin Console**](https://app.deepidv.com) and sign in.
  </Step>

  <Step title="Open API Keys">
    Navigate to [**Settings → API Keys**](https://app.deepidv.com/dashboard/api/api-keys) in the sidebar.
  </Step>

  <Step title="Copy your key">
    Your **API Key** will be displayed here. Click to copy it.
  </Step>
</Steps>

<Warning>
  **Your API key is a secret — treat it like a password.**

  It grants full access to the API on behalf of your organization. Never expose it in frontend code, public repositories, or client-side bundles. Always keep it server-side only.
</Warning>

***

## Base URL

All API requests are made against a single base URL:

```
https://api.deepidv.com
```

Every endpoint is prefixed with `/v1` — for example, `https://api.deepidv.com/v1/sessions`.

***

## Making Authenticated Requests

Include your secret API key in the `x-api-key` HTTP header with every request.

Here's an example of an authenticated request to the `Create Session` endpoint:

```bash cURL theme={null}
curl -X POST https://api.deepidv.com/v1/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+14165557890",
    "workflowId": "your-workflow-id"
  }'
```

deepidv validates your API key using HMAC SHA256 to authenticate the request and identify your organization.

***

## Rate Limits

The API enforces rate limits to ensure fair usage and platform stability:

| Limit               | Value  |
| ------------------- | ------ |
| Requests per second | 25     |
| Burst capacity      | 35     |
| Daily request quota | 10,000 |

If you exceed these limits, the API returns a `429 Too Many Requests` response. Implement exponential backoff in your integration to handle rate limiting gracefully.

***

## Error Handling

If your API key is missing or invalid, the API returns a `401 Unauthorized` response:

```json theme={null}
{
  "detail": "Invalid or missing API key"
}
```

| Status Code | Meaning                                                |
| ----------- | ------------------------------------------------------ |
| **401**     | API key is missing, invalid, or revoked                |
| **402**     | Insufficient token balance in your organization        |
| **403**     | API key does not have access to the requested resource |
| **429**     | Rate limit exceeded — back off and retry               |

<Tip>
  If you receive a `401` error, double-check that you're using the correct API key for your organization and that it hasn't been regenerated since you last copied it.
</Tip>