Authentication
Every request carries one bearer credential. For your own account that's an API key; for an app acting for other Phound users, it's an OAuth access token.
API keys
An API key is how your own code talks to your own Phound account. Send it on every request:
Authorization: Bearer ck_live_3f9a…
- Created in the dashboard. Sign in on the API keys page with your Phound account, name the key ("Production server", "Staging"), and choose its scopes.
- Shown once. The full key —
ck_live_followed by 48 hex characters — is in the create response and nowhere else. Afterwards you only ever see itshint, likeck_live_…a1b2, so you can tell keys apart. Lose one, and you revoke it and make another. - Revoking is immediate. A revoked key stops working on its next request. It stays in the list,
marked with
revoked_at. - One key per place it runs. Separate keys for production, staging and each service let you revoke one without touching the others.
A key can send messages that cost money. Never put one in a browser, a mobile app, or a repository. Load it from an environment variable or a secret manager.
Scopes
A key can do only what its scopes allow. Give each key just the ones it needs.
Scopes are named for what they cover, not for the API serving it. A resource with reads and changes has
:read and :write, and :write includes :read: a key that may change
something may also see it. What spends your balance has a scope of its own
(messages:send, numbers:buy, calls:stream) that includes nothing else.
Subscribing a webhook to an event needs the scope that reads what it carries.
The dashboard's key form names each scope for what it lets a key do, a level per resource: suppressions:write
is Suppressions → Write there, messages:send is Send messages. The table below gives each
scope's dashboard name, and an error for a scope a key lacks names both.
To see what a key may do, call GET https://api.phound.app/accounts/v1/introspect with it: any key can, whatever its
scopes.
Messaging API
| Scope | Grants | Endpoints |
|---|---|---|
messages:sendDashboard: Send messages charges balance |
Send messages, charged to your balance. | POST /conversations, POST /messages, POST /messages/preview, POST /messages/{id}/cancel, POST /media |
messages:readDashboard: Messages → Read |
Read messages and conversations. Webhook events:
conversation.created, message.accepted, message.deleted, message.delivered, message.edited, message.failed, message.received, message.rejected, message.sent, message.unconfirmed. |
GET /conversations, GET /conversations/{id}, GET /conversations/{id}/messages, GET /messages, GET /messages/{id} |
suppressions:readDashboard: Suppressions → Read |
Read opt-outs and your suppressions. Webhook events:
opt_in.created, suppression.created, suppression.deleted. |
GET /suppressions, GET /suppressions/{id} |
suppressions:writeDashboard: Suppressions → Write |
Suppress addresses and remove your suppressions. Includes suppressions:read. |
POST /suppressions, DELETE /suppressions/{id} |
Account API
| Scope | Grants | Endpoints |
|---|---|---|
account:readDashboard: Account → Read |
Read your account and your 10DLC registration's status. | GET /account |
personas:readDashboard: Personas → Read |
Read your personas. | GET /personas, GET /personas/{id} |
contacts:readDashboard: Contacts → Read |
Read your contacts. | GET /contacts, GET /contacts/{id} |
numbers:readDashboard: Numbers → Read |
List your phone numbers. | GET /available-phone-numbers, GET /phone-numbers, GET /phone-numbers/{phone_number} |
numbers:writeDashboard: Numbers → Write |
Assign numbers to personas and relabel them. Includes numbers:read. |
PATCH /phone-numbers/{phone_number} |
numbers:buyDashboard: Buy numbers charges balance |
Buy and release numbers, charged to your balance. | POST /phone-numbers, DELETE /phone-numbers/{phone_number}, POST /phone-numbers/{phone_number}/restore |
webhooks:manageDashboard: Webhooks → Manage sends data out |
Manage webhooks and read their delivery log. | GET /webhooks, POST /webhooks, GET /webhooks/{id}, PATCH /webhooks/{id}, DELETE /webhooks/{id}, POST /webhooks/{id}/rotate-secret, POST /webhooks/{id}/test, GET /webhooks/{id}/deliveries, POST /webhook-deliveries/{id}/retry |
usage:readDashboard: Usage → Read |
Read your API usage and request log. | GET /usage, GET /api-requests |
Recordings API
| Scope | Grants | Endpoints |
|---|---|---|
recordings:readDashboard: Recordings → Read |
Read recordings, their files and tags. Webhook events:
call.recorded. |
GET /recordings, GET /recordings/{id}, GET /recording-tags, GET /recordings-feed, GET /storage-quota |
recordings:writeDashboard: Recordings → Write sends data out |
Change, delete and restore recordings, move them to Dropbox, publish the podcast feed. Includes recordings:read. |
PATCH /recordings/{id}, DELETE /recordings/{id}, POST /recordings/{id}/restore, PUT /recordings/{id}/dropbox, DELETE /recordings/{id}/dropbox, PUT /recordings-feed, DELETE /recordings-feed |
Calls API
| Scope | Grants | Endpoints |
|---|---|---|
calls:readDashboard: Calls → Read |
Read your call history. Webhook events:
call.completed. |
GET /calls, GET /calls/{id} |
voicemails:readDashboard: Voicemails → Read |
Listen to and read the voicemails left for your personas. Webhook events:
call.voicemail_received, call.voicemail_transcribed. |
GET /voicemails, GET /voicemails/{id} |
calls:streamDashboard: Stream calls charges balance |
Place calls and stream calls' audio to your own server (beta), charged to your balance. Webhook events:
live_call.answered, live_call.ended. |
GET /live-calls, POST /live-calls, GET /live-calls/{live_call_id}, POST /live-calls/{live_call_id}/hangup |
call_settings:readDashboard: Call settings → Read |
Read your call flows, which one answers each persona, and its voicemail settings. | GET /flows, GET /flows/{id}, GET /personas/{persona_id}/flow, GET /personas/{persona_id}/voicemail |
call_settings:writeDashboard: Call settings → Write charges balance |
Change how a persona's calls are answered: its flow, including forwarding, its voicemail and greeting. Includes call_settings:read. |
PUT /personas/{persona_id}/flow, PATCH /personas/{persona_id}/voicemail, PUT /personas/{persona_id}/voicemail/greeting |
Managing keys
The Account API's /api-keys endpoints need the keys:manage scope, which no API key can
have. They accept only a signed-in Phound user — which is what the dashboard is. That way a leaked key can't mint
more keys.
Acting for other Phound users (OAuth)
If you're building an app that other Phound users connect to — a CRM integration, a connector — it doesn't hold their API keys. Instead, each user signs in with Phound and your app gets an OAuth 2.0 access token that acts for that one user.
- Your app is registered with Phound as a client app, with the scopes it needs. Scopes are granted to the app at registration, the same for every user who signs in to it. Contact Phound to register one.
- You send the user to Phound's authorization page (the standard authorization-code flow). They sign in, and
Phound redirects back to you with a
code. - You exchange the code for an access token and a refresh token, from your server, with your client secret.
- You call the APIs with
Authorization: Bearer <access token>, exactly as with a key. Requests act on that user's account.
Refresh the access token with its refresh token before it expires; an expired one is refused with
401.
When it doesn't work
| Status | code | Means | What to do |
|---|---|---|---|
401 | unauthorized |
No credential, or it's invalid, revoked or expired. | Check the Authorization: Bearer header and that the key is active. Don't retry as-is. |
403 | forbidden |
The credential is valid but lacks the scope. detail names the missing one. |
Create a key with that scope. |
403 | account_not_provisioned |
The account isn't set up for the API yet. | The account owner needs to finish setup; retrying won't help. |