API reference
API authentication
Ruut Voice exposes two API surfaces — the Twilio-compatible REST API and the carrier management API — each with its own authentication model.
Twilio-compatible API (Basic auth)
The /2010-04-01 endpoints are authenticated with HTTP Basic auth using your Account SID and Auth Token:
Basic authbash
# Account SID is the username, Auth Token is the password
curl "https://voice.ruut.chat/2010-04-01/Accounts/$RUUT_ACCOUNT_SID/Calls" \
-u "$RUUT_ACCOUNT_SID:$RUUT_AUTH_TOKEN"Failed authentication returns 401 Unauthorized.
Scoped API keys
Instead of the master Auth Token, create scoped API keys in the dashboard. Each key is an OAuth2 bearer token restricted to specific resources and scopes, and can be revoked independently.
Account scopes (Twilio API)
| Parameter | Type | Description |
|---|---|---|
phone_calls_read / write | Read / create / update calls. | |
messages_read / write | Read / send / update / delete messages. | |
incoming_phone_numbers_read / write | Read / provision / update numbers. | |
recordings_read / write | Read recordings and transcripts. | |
agent_extensions_read / write | Read / manage agent extensions. |
Use a scoped key with an OAuth2 bearer token:
Bearer tokenbash
curl "https://voice.ruut.chat/2010-04-01/Accounts/$RUUT_ACCOUNT_SID/Calls" \
-H "Authorization: Bearer $API_KEY"Carrier scope
The /carrier/v1 management API requires a carrier-scoped key with the carrier_api scope:
Carrier APIbash
curl "https://voice.ruut.chat/carrier/v1/accounts" \
-H "Authorization: Bearer $CARRIER_API_KEY"Best practices
- Use scoped keys with the minimum permissions your integration needs.
- Store keys server-side only; never embed them in client code.
- Rotate keys on a schedule and revoke any that leak.
- Webhooks are signed separately with HMAC — see webhooks.
The Auth Token and scoped keys are secrets. A leaked token lets anyone act as your account up to the token's scope.