Phone.inc

Authentication

The Phone.inc API uses API keys for authentication. Generate one in the dashboard, attach it to every request, and you're done.

API keys are the right choice when you are the customer — your scripts, internal tools, and server-to-server integrations all act on behalf of your own company.

If you're building a product that needs to act on behalf of other Phone.inc customers, you want OAuth 2.0 instead. See OAuth 2.0 for partners.

The base URL for everything below is https://app.phone.inc.

Create an API key

  1. Sign in to your Phone.inc dashboard.
  2. Open Your account → API Keys in the sidebar, or go directly to https://app.phone.inc/api_keys.
  3. Click Create API key, give it a descriptive name (e.g. Zapier integration, Reporting script), and submit.
  4. Copy the token immediately. It's shown to you exactly once. We store an HMAC-SHA256 digest, not the raw value, so we cannot show it to you again — losing it means creating a new one.

Tokens have the form phk_ followed by 28 base58 characters, e.g. phk_a1B2c3D4e5F6g7H8j9K1m2N3p4Q5r6S7.

Treat API keys like passwords. Never commit them to version control, never paste them into a public chat, and never embed them in client-side code (mobile apps, browser bundles). If a key leaks, revoke it and create a new one.

Use an API key

Send the token on every request to /api/v1/*. We accept three methods, in priority order:

  • Name
    X-Api-Key header
    Type
    recommended
    Description

    X-Api-Key: phk_... — explicit and unambiguous. Use this for new integrations.

  • Name
    Authorization: Bearer header
    Type
    supported
    Description

    Authorization: Bearer phk_... — works if your HTTP client has built-in Bearer support. Phone.inc auto-detects API keys vs OAuth tokens by the phk_ prefix.

  • Name
    api_key query parameter
    Type
    discouraged
    Description

    ?api_key=phk_... — supported for compatibility with tools that can't set headers. Avoid when possible: query strings end up in server logs and browser history.

Authenticated request

GET
/api/v1/main_numbers
curl https://app.phone.inc/api/v1/main_numbers \
  -H "X-Api-Key: phk_a1B2c3D4e5F6g7H8j9K1m2N3p4Q5r6S7"

Every key is scoped to the company that created it. Calls, voicemails, main numbers — everything you fetch comes from that company.

Rotate a key

We don't expire keys automatically. Rotate them whenever you change who has access (e.g. when an employee leaves) or after a suspected leak:

  1. Create a new key with the same name plus a date suffix.
  2. Deploy the new key to your integration.
  3. Confirm traffic is flowing under the new key (check Last used in the dashboard).
  4. Revoke the old one.

This rotate-then-revoke pattern keeps your integration online during the swap.

Revoke a key

Revoke a key any time from the dashboard:

  1. Open https://app.phone.inc/api_keys.
  2. Find the key in the list — you'll see its name, masked prefix (e.g. phk_a1B2c3D4…), creator, and when it was last used.
  3. Click Revoke and confirm.

Revocation takes effect immediately. The next request using that token returns 401 Invalid API key.

Errors

  • Name
    401 Unauthorized
    Description

    The token is missing, malformed, doesn't exist, or has been revoked. The body is {"error": "Invalid API key"}. Don't retry — fix the token.

  • Name
    429 Too Many Requests
    Description

    More than 10 invalid-key attempts from the same IP in 60 seconds. Subsequent requests are blocked for 60 seconds with {"error": "Too many failed API key attempts. Wait a moment and try again."} and a Retry-After: 60 header. This applies only to failed lookups — valid keys are never throttled here.

See Errors for the full status-code reference.

Security checklist

  • Store keys in environment variables or a secret manager — never in source control.
  • Use a separate key per integration, named after the integration. When something goes wrong, you can revoke just the affected one.
  • Review the Last used at and Last used IP columns in the dashboard periodically. If a key shows traffic from somewhere unexpected, rotate it.
  • Don't ship API keys in mobile apps or single-page apps. Anyone who can read your binary or browser bundle can read the key. Use OAuth instead — see OAuth 2.0 for partners.

Building a multi-tenant integration?

If you're building a product that other Phone.inc customers will install (a Slack bot, a CRM connector, an analytics service), API keys won't work — every customer would have to paste a key into your UI, and you'd be holding hundreds of credentials. That's what OAuth 2.0 is for.

Read the OAuth 2.0 guide