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

# Authentication

> How to authenticate with the Ringyo AI API

# Authentication

All API requests to Ringyo AI require authentication using an API key. This guide explains how to create, manage, and use API keys.

## API Keys

API keys are used to authenticate requests to the Ringyo AI API. Each key has specific permissions and rate limits based on your plan.

### Plan Requirements

| Plan       | API Access | Rate Limit    | Max Keys  |
| ---------- | ---------- | ------------- | --------- |
| Trial      | ❌          | -             | -         |
| Starter    | ❌          | -             | -         |
| **Pro**    | ✅          | 300 req/min   | 5         |
| **Agency** | ✅          | 1,000 req/min | Unlimited |

<Info>
  API access is available on Pro and Agency plans. [Upgrade your plan](https://www.ringyo.ai/pricing) to get started.
</Info>

## Creating an API Key

<Steps>
  <Step title="Open Developer Settings">
    Go to your [Ringyo AI Dashboard](https://www.ringyo.ai/dashboard) and click **Developers** in the sidebar.
  </Step>

  <Step title="Create New Key">
    Click **Create Key** and provide:

    * **Name**: A descriptive name (e.g., "Production", "n8n Integration")
    * **Permissions**: Select which actions the key can perform
  </Step>

  <Step title="Save Your Key">
    <Warning>
      Your API key will only be displayed once. Copy and store it securely before closing the dialog.
    </Warning>
  </Step>
</Steps>

## Using Your API Key

Include your API key in the `Authorization` header of every request:

```bash theme={null}
Authorization: Bearer vb_live_YOUR_API_KEY
```

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.ringyo.ai/v1/agents \
    -H "Authorization: Bearer vb_live_YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.ringyo.ai/v1/agents', {
    headers: {
      'Authorization': 'Bearer vb_live_YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.ringyo.ai/v1/agents',
      headers={
          'Authorization': 'Bearer vb_live_YOUR_API_KEY',
          'Content-Type': 'application/json'
      }
  )
  ```
</CodeGroup>

## Key Permissions

API keys can be scoped to specific permissions:

| Permission           | Description                     |
| -------------------- | ------------------------------- |
| `calls:read`         | View call history and details   |
| `calls:write`        | Initiate outbound calls         |
| `agents:read`        | View voice agent configurations |
| `agents:write`       | Create and modify voice agents  |
| `contacts:read`      | View contacts                   |
| `contacts:write`     | Create and modify contacts      |
| `appointments:read`  | View appointments               |
| `appointments:write` | Create and modify appointments  |
| `phone_numbers:read` | View phone numbers              |
| `analytics:read`     | View analytics and reports      |
| `webhooks:manage`    | Manage webhook endpoints        |

<Tip>
  Follow the principle of least privilege. Only grant the permissions your integration actually needs.
</Tip>

## Rate Limiting

API requests are rate-limited based on your plan:

* **Pro**: 300 requests per minute
* **Agency**: 1,000 requests per minute

When you exceed your rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}
```

### Best Practices

1. **Implement exponential backoff** for retries
2. **Cache responses** where appropriate
3. **Use webhooks** instead of polling for real-time updates
4. **Batch operations** when possible

## Key Security

<Warning>
  **Never expose your API key in client-side code.** API keys should only be used in server-side applications.
</Warning>

### Security Best Practices

1. **Store keys securely** — Use environment variables, not code
2. **Rotate regularly** — Generate new keys periodically
3. **Use separate keys** — Different keys for production/staging
4. **Monitor usage** — Review API logs for suspicious activity
5. **Revoke compromised keys** — Immediately revoke any exposed keys

## Revoking a Key

If a key is compromised or no longer needed:

1. Go to **Dashboard → Developers**
2. Find the key you want to revoke
3. Click the **Revoke** button
4. Confirm the action

<Warning>
  Revoking a key is immediate and permanent. Any applications using that key will stop working.
</Warning>

## Troubleshooting

### Common Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The API key is missing, invalid, or revoked.

    **Solution**: Check that you're including the `Authorization` header with a valid key.
  </Accordion>

  <Accordion title="403 Forbidden">
    The API key doesn't have permission for this action.

    **Solution**: Update the key's permissions or create a new key with the required permissions.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    You've exceeded your rate limit.

    **Solution**: Wait for the `retry_after` period, then retry with exponential backoff.
  </Accordion>
</AccordionGroup>

## Need Help?

If you're having trouble with authentication:

* Check our [API Reference](/api-reference/introduction)
* Join our [Discord community](https://ringyo.ai/contact)
* Contact [support@ringyo.ai](mailto:support@ringyo.ai)