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

# API Key Authentication for VoiceInfra REST Requests

> VoiceInfra API uses API keys passed in the X-API-Key header. Generate and manage keys from your dashboard under Settings > API Keys.

Every request to the VoiceInfra API must be authenticated with an API key. You pass the key in the `X-API-Key` request header — there are no OAuth flows or session tokens. Keep your keys secret: anyone who holds a valid key can make API calls on your account's behalf.

## Getting your API key

<Steps>
  <Step title="Log in to your VoiceInfra dashboard">
    Go to [portal.voiceinfra.ai](https://portal.voiceinfra.ai) and sign in to your account.
  </Step>

  <Step title="Navigate to Settings → API Keys">
    Open the **Settings** menu from the left sidebar and select **API Keys**.
  </Step>

  <Step title="Click Generate New Key">
    Click the **Generate New Key** button. Give the key a descriptive name (for example, `production-crm` or `staging-tests`) so you can identify it later.
  </Step>

  <Step title="Copy the key immediately">
    Your new API key is displayed only once. Copy it now and store it somewhere safe — you will not be able to retrieve it again from the dashboard.
  </Step>

  <Step title="Store it securely">
    Add the key to your environment variables, a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or Doppler), or your CI/CD pipeline's secret store. Never hard-code it in your source files.
  </Step>
</Steps>

<Warning>
  Your API key is shown only once at creation time. If you lose it, you must generate a new one and update every integration that uses the old key.
</Warning>

## Using your API key

Pass the key in the `X-API-Key` header on every request. The header name is **case-sensitive**.

```bash cURL example theme={null}
curl -X POST https://api.voiceinfra.ai/v1/calls/outbound \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_abc123", "from_number": "+18005551234", "to_number": "+14155550100"}'
```

## Multiple API keys

You can create as many API keys as you need. A common pattern is to create one key per environment or integration:

* **`production-crm`** — used by your CRM to trigger live customer calls
* **`staging-automation`** — used during QA and testing
* **`zapier-integration`** — scoped to a specific no-code workflow

Because each key is independent, you can revoke a single key without disrupting your other integrations.

## Revoking a key

1. Go to **Settings → API Keys** in your dashboard.
2. Find the key you want to remove.
3. Click **Revoke**.

Revoked keys stop working immediately — any in-flight request using a revoked key receives `401 Unauthorized`.

## Security best practices

<AccordionGroup>
  <Accordion title="Never embed keys in client-side code or version control">
    API keys in front-end JavaScript or committed to a Git repository are effectively public. Always load keys from environment variables or a secrets manager at runtime on your server.
  </Accordion>

  <Accordion title="Use environment variables or a secrets manager">
    Reference your key as `process.env.VOICEINFRA_API_KEY` (Node.js) or `os.environ['VOICEINFRA_API_KEY']` (Python). For production workloads, use a dedicated secrets manager with access controls and audit logging.
  </Accordion>

  <Accordion title="Create separate keys per service or environment">
    Scope each key to a single use case. This limits the blast radius if a key is compromised and makes it easy to rotate or revoke without affecting unrelated integrations.
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Generate a replacement key, update your integration, verify it works, then revoke the old key. Aim to rotate keys at least every 90 days or immediately after a suspected exposure.
  </Accordion>

  <Accordion title="Revoke unused keys promptly">
    If a key was created for a project that has ended, revoke it. Dormant keys are unnecessary risk.
  </Accordion>
</AccordionGroup>

## Authentication errors

If a request fails authentication, the API returns `401 Unauthorized` with the following error body:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}
```

Common causes and fixes:

* **Missing header** — make sure the request includes `X-API-Key`. The header name is case-sensitive; `x-api-key` or `X-Api-Key` will not work.
* **Invalid key** — double-check the key value. Copy it directly from your password manager or secrets store to avoid introducing extra whitespace or truncated characters.
* **Revoked key** — if the key was revoked, generate a new one and update your integration.