{"issuer":"https://api.telnyx.com","authorization_endpoint":"https://portal.telnyx.com/oauth/authorize","token_endpoint":"https://api.telnyx.com/oauth/token","registration_endpoint":"https://portal.telnyx.com/oauth/register","scopes_supported":["read","write","admin"],"response_types_supported":["code","token"],"grant_types_supported":["authorization_code","client_credentials","refresh_token"],"token_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post"],"revocation_endpoint":"https://api.telnyx.com/oauth/revoke","revocation_endpoint_auth_methods_supported":["client_secret_basic"],"code_challenge_methods_supported":["S256"],"jwks_uri":"https://api.telnyx.com/.well-known/jwks.json","agent_auth":{"identity_endpoint":"https://api.telnyx.com/v2/bot_signup","register_uri":"https://telnyx.com/agent-signup.md","claim_uri":"https://telnyx.com/agent-signup.md","revocation_uri":"https://telnyx.com/auth.md","auth_md":"https://telnyx.com/auth.md","skill":"https://telnyx.com/auth.md","protected_resource_metadata_uri":"https://telnyx.com/.well-known/oauth-protected-resource","grants_supported":["authorization_code","client_credentials","refresh_token","x402_pay_per_call"],"identity_types_supported":["service_auth","anonymous"],"events_supported":["credential_issued","credential_revoked"],"service_auth":{"credential_types_supported":["bearer_api_key","oauth_pkce"],"registration_endpoint":"https://api.telnyx.com/v2/bot_signup","challenge_endpoint":"https://api.telnyx.com/v2/bot_challenge","claim":"magic_link_email","runbook":"https://telnyx.com/agent-signup.md"},"anonymous":{"credential_types_supported":["x402_pay_per_call"]},"identity_assertion_supported":false},"agent_walkthrough":{"_description":"Step-by-step procedure for an AI agent or M2M (machine-to-machine) client to obtain, present, and revoke credentials against the Telnyx API. The full prose walkthrough lives at /auth.md; this inline block is the agent-discovery summary.","auth_md":"https://telnyx.com/auth.md","methods":["bearer_api_key","oauth_pkce","x402_pay_per_call"],"steps":[{"step":1,"name":"Discover","action":"GET https://telnyx.com/.well-known/oauth-authorization-server to read this AS metadata document. Inspect the agent_auth block for identity_endpoint (where to POST to register) / register_uri / claim_uri / revocation_uri / auth_md. For the protected-resource metadata (resource server URLs, supported scopes), GET https://telnyx.com/.well-known/oauth-protected-resource.","method":"GET","endpoint":"https://telnyx.com/.well-known/oauth-authorization-server"},{"step":2,"name":"Pick a method","action":"Long-running agents with a stable account → Method 3 (Bearer API key, M2M / client_credentials). Multi-user agent platforms (Cursor, Claude, ChatGPT extensions) → Method 4 (OAuth 2.0 + PKCE). One-off inference without signup → Method 5 (x402 pay-per-call on Base mainnet)."},{"step":3,"name":"Register / Mint a Bearer API key (bot-challenge signup, requires email)","action":"GET https://telnyx.com/agent-signup.md returns the obfuscated-math bot-challenge runbook. Steps in order: (1) POST https://api.telnyx.com/v2/bot_challenge to fetch the challenge. (2) Solve the challenge with the LLM agent. (3) POST https://api.telnyx.com/v2/bot_signup with the answer + email. A magic-link is then sent to that email — the agent (or human operator) must follow the magic-link to receive a temporary session token. (4) Use the session token as Bearer to POST https://api.telnyx.com/v2/api_keys, which mints the long-lived API key. End-to-end-autonomous only when the agent has programmatic email access; otherwise a human pastes the magic-link.","method":"POST","endpoint":"https://api.telnyx.com/v2/bot_signup","request_body_template":{"bot_challenge_nonce":"{{nonce from POST /v2/bot_challenge}}","bot_challenge_answer":"{{numeric answer from LLM}}","terms_and_conditions_url":"{{terms_and_conditions_url from POST /v2/bot_challenge response}}","privacy_policy_url":"{{privacy_policy_url from POST /v2/bot_challenge response}}","email":"{{user/agent email}}","terms_of_service":true},"notes":["Magic-link email step is currently the only path to obtain a session token after bot_signup.","Without email access the flow falls back to: user pastes the magic-link URL into the agent's prompt.","Full prose: see Step 4 (Path A / Path B) in /agent-signup.md."]},{"step":"3a","name":"OR: OAuth 2.0 client_credentials (M2M with a pre-registered client)","action":"If you already have a registered OAuth client (registration_endpoint at https://portal.telnyx.com/oauth/register), use grant_type=client_credentials to mint a token in one round-trip. Form-encoded body: client_id, client_secret, grant_type=client_credentials. Returns access_token + token_type=Bearer + expires_in.","method":"POST","endpoint":"https://api.telnyx.com/oauth/token","request_body_template":{"grant_type":"client_credentials","client_id":"{{your_client_id}}","client_secret":"{{your_client_secret}}"}},{"step":"3b","name":"OR: OAuth 2.0 authorization_code + PKCE — authorize (user-delegated)","action":"For a multi-user agent platform, redirect the user's browser to https://portal.telnyx.com/oauth/authorize with the query parameters below. The user signs in and consents; Telnyx redirects back to <redirect_uri> with ?code=<authorization_code>&state=<csrf>. This step is a browser redirect, not an API call — no request body. Then exchange the code at the token endpoint in step 3c.","method":"GET","endpoint":"https://portal.telnyx.com/oauth/authorize","query_params_template":{"response_type":"code","client_id":"{{your_client_id}}","code_challenge":"{{S256(code_verifier)}}","code_challenge_method":"S256","redirect_uri":"{{your_cb}}","state":"{{csrf_token}}","scope":"{{space_separated_scopes}}"}},{"step":"3c","name":"OR: OAuth 2.0 authorization_code + PKCE — token exchange","action":"Exchange the authorization code from step 3b for an access token. Telnyx's token endpoint advertises `client_secret_basic` and `client_secret_post` in `token_endpoint_auth_methods_supported`, so client authentication is REQUIRED in addition to PKCE — send client_id + client_secret either via HTTP Basic auth header (client_secret_basic) or in the form-encoded body (client_secret_post). PKCE alone is NOT sufficient; the client_secret is also required.","method":"POST","endpoint":"https://api.telnyx.com/oauth/token","request_body_template":{"grant_type":"authorization_code","code":"{{code from authorize redirect in step 3b}}","code_verifier":"{{the PKCE verifier}}","redirect_uri":"{{your_cb}}","client_id":"{{your_client_id}}","client_secret":"{{your_client_secret — sent via Basic auth header (client_secret_basic) OR body (client_secret_post)}}"}},{"step":4,"name":"Use the bearer credential","action":"Set `Authorization: Bearer <access_token>` on every request to https://api.telnyx.com/v2/* — covers Voice, Messaging, Numbers, Inference, MCP tools, and the agent-runtime surface. Token TTL for OAuth-issued tokens is `expires_in` from the token response; API keys do not expire until revoked.","method":"GET","endpoint":"https://api.telnyx.com/v2/balance"},{"step":5,"name":"x402 pay-per-call (no registration, no Bearer token)","action":"For one-shot inference, POST to https://x402.telnyx.com/v1/chat/completions without auth. The server replies with HTTP 402 and a payment-required quote in the response header. Sign the quote (EIP-3009 USDC on Base mainnet) and retry with X-Payment: <signed-quote>. Discovery doc: https://telnyx.com/.well-known/x402.","method":"POST","endpoint":"https://x402.telnyx.com/v1/chat/completions"},{"step":6,"name":"Refresh (OAuth only)","action":"POST https://api.telnyx.com/oauth/token with grant_type=refresh_token + refresh_token + client authentication. As with token exchange in step 3c, the token endpoint requires client_secret_basic (HTTP Basic header with client_id:client_secret) or client_secret_post (client_id + client_secret in the body) per token_endpoint_auth_methods_supported above — refresh is not available for clients without a secret. Bearer API keys (Method 3) do not refresh — they're long-lived until revoked.","method":"POST","endpoint":"https://api.telnyx.com/oauth/token","request_body_template":{"grant_type":"refresh_token","refresh_token":"{{your_refresh_token}}","client_id":"{{your_client_id}}","client_secret":"{{your_client_secret — sent via Basic auth header (client_secret_basic) OR body (client_secret_post)}}"}},{"step":7,"name":"Revoke","action":"Bearer API keys: DELETE https://api.telnyx.com/v2/api_keys/{id} (or revoke from the portal). OAuth tokens: POST https://api.telnyx.com/oauth/revoke with token=<access_or_refresh_token>. Revocation is immediate; in-flight requests with the revoked credential return 401. Full prose: https://telnyx.com/auth.md#revocation.","method":"POST","endpoint":"https://api.telnyx.com/oauth/revoke"}],"errors":{"401_invalid_token":{"status":401,"www_authenticate":"Bearer realm=\"Telnyx API\", error=\"invalid_token\"","meaning":"Credential missing, malformed, expired, or revoked. Re-register at agent_auth.identity_endpoint (runbook: agent_auth.register_uri) or refresh via grant_type=refresh_token."},"401_insufficient_scope":{"status":401,"www_authenticate":"Bearer error=\"insufficient_scope\"","meaning":"Credential is valid but lacks the scope for this endpoint. Re-run the OAuth flow with the requested scope; for API keys, check account permissions."},"402_payment_required":{"status":402,"header":"payment-required: <EIP-3009 quote>","meaning":"x402 endpoint requires payment; no auth was sent. Sign the quote and retry with X-Payment header."},"429_rate_limited":{"status":429,"retry_after_header":"Retry-After: <seconds>","meaning":"Rate-limited. Honor RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset response headers (RFC 9598) to self-throttle."}}}}