Docs / Guides

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 its hint, like ck_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.
Keep keys on your server

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

ScopeGrantsEndpoints
messages:send
Dashboard: Send messages
charges balance
Send messages, charged to your balance. POST /conversations, POST /messages, POST /messages/preview, POST /messages/{id}/cancel, POST /media
messages:read
Dashboard: 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:read
Dashboard: Suppressions → Read
Read opt-outs and your suppressions. Webhook events: opt_in.created, suppression.created, suppression.deleted. GET /suppressions, GET /suppressions/{id}
suppressions:write
Dashboard: Suppressions → Write
Suppress addresses and remove your suppressions. Includes suppressions:read. POST /suppressions, DELETE /suppressions/{id}

Account API

ScopeGrantsEndpoints
account:read
Dashboard: Account → Read
Read your account and your 10DLC registration's status. GET /account
personas:read
Dashboard: Personas → Read
Read your personas. GET /personas, GET /personas/{id}
contacts:read
Dashboard: Contacts → Read
Read your contacts. GET /contacts, GET /contacts/{id}
numbers:read
Dashboard: Numbers → Read
List your phone numbers. GET /available-phone-numbers, GET /phone-numbers, GET /phone-numbers/{phone_number}
numbers:write
Dashboard: Numbers → Write
Assign numbers to personas and relabel them. Includes numbers:read. PATCH /phone-numbers/{phone_number}
numbers:buy
Dashboard: 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:manage
Dashboard: 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:read
Dashboard: Usage → Read
Read your API usage and request log. GET /usage, GET /api-requests

Recordings API

ScopeGrantsEndpoints
recordings:read
Dashboard: 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:write
Dashboard: 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

ScopeGrantsEndpoints
calls:read
Dashboard: Calls → Read
Read your call history. Webhook events: call.completed. GET /calls, GET /calls/{id}
voicemails:read
Dashboard: 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:stream
Dashboard: 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:read
Dashboard: 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:write
Dashboard: 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.

  1. 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.
  2. 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.
  3. You exchange the code for an access token and a refresh token, from your server, with your client secret.
  4. 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

StatuscodeMeansWhat to do
401unauthorized 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.
403forbidden The credential is valid but lacks the scope. detail names the missing one. Create a key with that scope.
403account_not_provisioned The account isn't set up for the API yet. The account owner needs to finish setup; retrying won't help.