Project BlueMint a token
Exchange your API key for a 15-minute voice token pinned to one line. Call this from your server whenever the SDK's tokenProvider asks, and return the body to the browser as-is.
POSThttps://app.tryprojectblue.com/api/v1/dialer/tokenBearer token
On this page
Server to server only
The request carries your workspace API key, so it must never be made from a browser or a mobile app. Put an authenticated route in front of it on your own backend — the snippets in the rail are complete examples — and have that route decide which
lineId the signed-in user may call from.Headers
Authorization: Bearer YOUR_API_KEY and Content-Type: application/json. The same key you use against api.tryprojectblue.com.
Request body
lineIdstringRequiredThe line to call from, exactly as returned by GET https://api.tryprojectblue.com/get-lines with the same API key. Calls are placed from that line's number and count toward its dialer plan. Shared and trial lines are refused.
Response
tokenstringRequiredOpaque, short-lived voice token scoped to one line. Hand the whole response body to the SDK's tokenProvider; never store the token or build on its contents.
expiresAtstring (ISO 8601)RequiredWhen the token stops working. Always 15 minutes from mint.
ttlSecondsnumberRequiredToken lifetime in seconds. Currently 900.
lineIdstringRequiredThe line this token is pinned to, echoed back.
inboundEnabledbooleanRequiredWhether this token can also receive calls. True only when the line has an inbound number and someone in your workspace is in its ring set. Can differ from one mint to the next.
maxCallsPerTokennumberRequiredOutbound calls one token may place before it must be refreshed. Currently 10. The SDK refreshes ahead of this limit, so you never hit it in normal use.
allowanceobject | nullRequiredToday's minute allowance for the workspace and for this line. Null only when the plan could not be read at mint time; the token is still valid.
state"ok" | "soft" | "hard"Requiredok: within plan. soft: near the included minutes — warn your users. hard is never returned on a 200; a hard stop is a 402 dialer_cap_reached refusal instead.
usednumberRequiredWhole minutes used today across the workspace.
includednumberRequiredMinutes included in today's plan across the workspace.
capnumber | nullRequiredWorkspace ceiling in minutes for today. Null when the account has no cap.
pctnumberRequiredused ÷ included, as a whole percent.
periodEndstring (ISO 8601)RequiredWhen today's allowance resets — midnight UTC. A capped line resumes calling at this time.
lineobject | nullRequiredThis line's own standing against its daily cap.
usednumberRequiredMinutes this line has used today.
capnumber | nullRequiredThis line's daily cap in minutes, or null for none.
cappedbooleanRequiredTrue when this line has hit its cap. The next mint for it returns 402 even if the workspace still has minutes.
Forward it unchanged
Return the upstream status, body, and Retry-After header to the browser exactly as received. The SDK reads expiresAt, maxCallsPerToken, inboundEnabled, and allowance to schedule its own refreshes and to raise typed errors. If you reshape the body, refresh timing and error handling degrade to defaults.
Guard the .json() call. A proxy in front of the app can return a non-JSON 502 or 503, and an unhandled throw in your route becomes a generic 500 in the browser instead of a retryable token_unavailable.
Refusals
Every non-2xx body is { error, code }, plus extra fields on the cap and rate-limit cases. Unlike the messaging API, code is always present here, and the SDK maps it to a DialerError code for you.
Status
code
SDK code
Meaning
401invalid_api_keytoken_unavailableMissing, revoked, or wrong API key.
400invalid_line_idline_unavailablelineId missing or not a value from /get-lines. Refused before the rate-limit slot is spent.
404line_not_foundline_unavailableNot one of this workspace's lines. Returned for other workspaces' lines too — existence is never confirmed.
403line_inbound_onlyline_unavailableThe line receives calls but cannot place them.
403line_not_eligibleline_unavailableShared and trial lines are not an SDK surface.
403dialer_subscription_requiredsubscription_requiredNo Dialer add-on on the workspace.
402account_paywalledaccount_paywalledThe account is past due.
402dialer_cap_reachedcap_reachedThe workspace or this line has used today's minutes. Body carries used, included, cap, periodEnd.
404dialer_not_provisionednot_provisionedBusiness registration (Phone Compliance) not yet approved, so calling is not provisioned.
403api_key_unsupportedtoken_unavailableA legacy key that cannot mint. Create a new key in Settings → API Keys.
429rate_limitedrate_limitedToo many mints for this key. Body carries retryAfterSeconds; a Retry-After header is set.
500dialer_misconfiguredtoken_unavailableCalling is not fully configured for this account. Contact support.
503dialer_unavailabletoken_unavailableToken service temporarily unavailable. Retry with backoff.
The mint has its own rate limit
This endpoint allows 30 mints per minute per API key, separate from the 60 requests per minute on the messaging API. A well-behaved SDK session mints once at start, then roughly once every 14 minutes and once per 10 calls, so the limit only matters if your server mints on every page load. Malformed requests are refused before they consume a slot.
Status codes
- 200
- Token minted
- 400
- invalid_line_id
- 401
- invalid_api_key
- 402
- dialer_cap_reached or account_paywalled
- 403
- dialer_subscription_required, line_inbound_only, line_not_eligible, api_key_unsupported
- 404
- line_not_found or dialer_not_provisioned
- 429
- rate_limited — read retryAfterSeconds
- 500
- dialer_misconfigured or internal_error
- 503
- dialer_unavailable — retry with backoff