Customer API authentication

Request, use, protect, and rotate a Steer Phones API key, and understand what its scopes allow.

Every approved customer API request carries a secret API key in the X-API-Key header. The key identifies one phone system and one set of permissions — it is not a user login, and it does not inherit whatever the person who requested it can do in the dashboard. Understanding that boundary is most of what you need to integrate safely.

Anatomy of a key

A secret key looks like sk_phones_<short>_<secret>. The sk_phones_ prefix marks it as a secret server-side credential.

• One phone system. A key is bound to the phone system it was issued for. Using it against a different phone system is refused, so a multi-location integration needs one key per system.
• Fixed permissions. A key carries the scopes granted when it was issued (or a role Steer Phones bound it to). Nothing about the key escalates at runtime.
• Shown once. Only the hashed key is stored. After issuance, Steer Phones can show you the name, the prefix, and the last four characters — never the key itself. If it is lost, it is replaced, not recovered.
• Recorded on every use. The key’s last-used time and source address are kept, and every authenticated request is written to your activity records.

Send the key in the X-API-Key header. An Authorization: Bearer sk_phones_… header is also accepted for clients that can only set a bearer token.

Host: api.steerphones.com
X-API-Key: sk_phones_…
Accept: application/json

A separate key type exists for dynamic number insertion: publishable keys, prefixed pk_phones_, which are safe to place in the tracking snippet on a public web page. Publishable keys are rejected by the customer API — they can only reach the number-tracking service. Never treat the two as interchangeable, and never put an sk_phones_ key in a browser.

Request a key

Keys are provisioned by Steer Phones. There is no self-service page in the dashboard that creates one, so the flow is a conversation with your Steer Phones contact rather than a button.

Have this ready when you ask:

1. Which phone system the integration acts on. One key per system.
2. What the integration does, in one sentence — this drives which scopes are granted.
3. The narrowest scopes that do the job. Ask for read where you only read.
4. Source addresses, if your integration calls from fixed addresses. A key can be restricted to an allowlist so it is unusable from anywhere else.
5. An expiry date, if the integration is temporary. A key can be issued to expire automatically.

Steer Phones returns the key once, over a channel you agree on. Put it straight into your secret store.

Key issuance for the customer API opens together with the published operation reference, so if the reference has not been released yet, ask for webhooks (which need no key) and plan the rest.

What scopes allow

Scopes follow a resource:action shape — calls:read, contacts:write. Two rules matter when you ask for them:

• Write includes read. Granting contacts:write also grants contacts:read, so you never need both.
• Least privilege is enforceable. A request outside a key’s scopes is refused with a 403, whether or not the operation exists.

The resource areas most commonly granted to a customer key:

Scopes that reach across tenants are reserved for Steer Phones’ own operations and are never granted on a customer key. Neither can a key manage API keys — key lifecycle is never available to a key, only to an authorized person.

Keep a key safe

• Store it in a server-side secret manager and read it from configuration at runtime.
• Never place it in browser code, a mobile app, a URL query string, a support ticket, a screenshot, a spreadsheet, or source control.
• Send it only over HTTPS to https://api.steerphones.com. Do not send it to any other host, including a documentation site.
• Give each integration its own key. Shared keys make revocation an outage for everyone.
• Restrict the key to your integration’s source addresses when they are stable.

Treat a key that appeared anywhere unexpected as compromised and ask Steer Phones to revoke it. Revocation takes effect immediately.

Rotate a key

Rotation issues a replacement and gives the old key a short overlap period before it expires, so you can deploy the new value without a gap in service. Ask Steer Phones to roll the key, deploy the new value during the overlap, then confirm the old key stopped being used.

Rotate on a schedule for long-lived integrations, and immediately whenever someone with access to the key leaves, a laptop or CI system holding it is lost, or the value was pasted somewhere it should not have been. An expired or revoked key fails authentication outright rather than silently degrading.

See what a key did

Every authenticated request — allowed or denied — is recorded. In the dashboard, open Records > Activity and filter by API key to see what an integration reached, when, from which address, and whether it was permitted. Selecting a key opens its own history, including activity from the keys it replaced during rotation, so a rotation does not break the trail.

This is the first place to look when an integration behaves unexpectedly: a run of denied rows usually means a scope was not granted, and a gap usually means the integration stopped calling rather than the key failing.

Expected result

Your integration reads its key from a secret store, sends it in X-API-Key over HTTPS, and receives either data or a clear typed error. Nobody outside the integration ever sees the key value, and the activity records show exactly what it touched.

Troubleshooting

• 401 with an authentication code: The key is missing, mistyped, expired, or revoked. Confirm the header name and that the value has no whitespace or line breaks.
• 403 saying the key is not authorized for this phone system: The key belongs to another phone system. Use the key issued for the system you are calling about.
• 403 naming a missing scope: The key was not granted that permission. Ask Steer Phones to widen the scopes, or point the integration at what it is allowed to reach.
• 403 on a publishable key: A pk_phones_ key was sent to the customer API. Publishable keys work only with number tracking.
• Requests fail only from a new server: The key has a source-address allowlist that does not include the new address.
• 429 responses: You are above the request rate for that key. See API versioning and errors.

Related guidance

• Customer API overview.
• API versioning and errors.
• Receive events with webhooks.
• Review account activity and changes.
• Configure dynamic number insertion.