Skip to main content

​
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

PlanAPI AccessRate LimitMax Keys
Trial❌--
Starter❌--
Pro✅300 req/min5
Agency✅1,000 req/minUnlimited
API access is available on Pro and Agency plans. Upgrade your plan to get started.

​
Creating an API Key

1

Open Developer Settings

Go to your Ringyo AI Dashboard and click Developers in the sidebar.
2

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
3

Save Your Key

Your API key will only be displayed once. Copy and store it securely before closing the dialog.

​
Using Your API Key

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

​
Example Request

curl https://api.ringyo.ai/v1/agents \
  -H "Authorization: Bearer vb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Key Permissions

API keys can be scoped to specific permissions:
PermissionDescription
calls:readView call history and details
calls:writeInitiate outbound calls
agents:readView voice agent configurations
agents:writeCreate and modify voice agents
contacts:readView contacts
contacts:writeCreate and modify contacts
appointments:readView appointments
appointments:writeCreate and modify appointments
phone_numbers:readView phone numbers
analytics:readView analytics and reports
webhooks:manageManage webhook endpoints
Follow the principle of least privilege. Only grant the permissions your integration actually needs.

​
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: 
{
  "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

Never expose your API key in client-side code. API keys should only be used in server-side applications.

​
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
Revoking a key is immediate and permanent. Any applications using that key will stop working.

​
Troubleshooting

​
Common Errors

The API key is missing, invalid, or revoked.Solution: Check that you’re including the Authorization header with a valid key.
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.
You’ve exceeded your rate limit.Solution: Wait for the retry_after period, then retry with exponential backoff.

​
Need Help?

If you’re having trouble with authentication: