> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent authentication (auth.md)

> How AI agents obtain and use Telnyx API credentials — discovery, registration, claiming a key, usage, errors, and revocation.

This page is the machine-readable credential walkthrough for AI agents, published at the [auth.md convention](https://workos.com/auth-md) path. The Telnyx API-key flow below is not an implementation of the WorkOS agent registration protocol. It covers discovering authentication, registering a Telnyx account, obtaining an API key, using it, handling errors, and revoking it.

## Discover

1. Fetch [protected-resource metadata](https://api.telnyx.com/.well-known/oauth-protected-resource) (RFC 9728). Check `resource` and follow `authorization_servers`; the API currently advertises `https://api.telnyx.com`.
2. Fetch [authorization-server metadata](https://api.telnyx.com/.well-known/oauth-authorization-server) (RFC 8414). This describes OAuth endpoints and the optional `agent_auth` extension. OAuth client registration is not Telnyx account registration or API-key creation.
3. Check the advertised credential types and agent endpoints. The [WorkOS auth.md protocol](https://workos.com/auth-md/docs/auth-md) names `identity_endpoint` for agent registration, `claim_endpoint` for the user-claim ceremony, and `events_endpoint` for lifecycle events. The API currently publishes `agent_auth`, but does not advertise `identity_endpoint`, `claim_endpoint`, or `events_endpoint`. An `events_supported` list alone does not supply an events endpoint. If the block is absent or an endpoint required for a flow is missing, do not attempt that protocol flow; follow the [agent signup runbook](https://telnyx.com/agent-signup.md) for the Telnyx API-key flow below. Do not construct missing endpoints or POST to a Markdown document.

Unauthenticated `GET https://api.telnyx.com/v2/phone_numbers` returns `401` with a discovery hint:

```http theme={null}
WWW-Authenticate: Bearer resource_metadata="https://api.telnyx.com/.well-known/oauth-protected-resource"
```

This read-only probe does not create an account or provision a resource. Fetch the explicit metadata URLs above if a different endpoint does not return a discovery hint.

Machine-readable context: [llms.txt](/llms.txt) · [capabilities](https://telnyx.com/ai/capabilities.json) · [pricing](/pricing.md)

## Pick a method

* **API key:** use a server-side Bearer API key for an integration operating its own Telnyx account. Follow the lifecycle below.
* **Delegated access:** use the supported OAuth flow for integrations acting on behalf of an existing user. Follow the advertised authorization-server endpoints and the [remote MCP connection guide](/docs/development/mcp/remote-mcp) for MCP clients. OAuth client registration does not create a Telnyx account.
* **Other protocols:** follow [product-specific authentication](/docs/development/api-fundamentals/authentication#product-specific-authentication) for S3, WebRTC, and WebSockets; an API key is not universal across every protocol.

## Register

Obtain the account owner's authorization before creating an account or accepting terms. Email verification requires access to an approved mailbox or the owner's assistance. Do not create accounts, mailboxes, or billable resources solely to test authentication without authorization.

Fetch the [agent signup runbook](https://telnyx.com/agent-signup.md). This is documentation, not a registration endpoint. Follow its current challenge-response, signup, and email verification instructions; availability and regional restrictions can apply. If signup is unavailable, use [interactive signup](https://telnyx.com/sign-up) with the account owner rather than guessing replacement endpoints.

## Claim the credential

The signup runbook documents the programmatic sequence:

1. Complete email verification using the single-use sign-in link. Treat the link as a secret; automated link checking can consume it.
2. Read the temporary session token from `data.api_v2_token` in the verification response.
3. Use that token with the runbook's `POST https://api.telnyx.com/v2/api_keys` request to create the API key.
4. Store the returned `data.api_key` in a secret manager or protected server-side environment as `TELNYX_API_KEY`. The temporary session token is not the permanent API key.

For an existing account, create or manage keys through [API Keys in Mission Control Portal](https://portal.telnyx.com/#/app/api-keys). This browser page is not an API endpoint. Do not log keys, tokens, or verification links, or place them in browser code, repositories, URLs, or chat messages.

## Use the credential

With `TELNYX_API_KEY` set in the server-side environment, make a read-only request:

```bash theme={null}
curl --request GET \
  --url "https://api.telnyx.com/v2/phone_numbers" \
  --header "Authorization: Bearer $TELNYX_API_KEY" \
  --header "Accept: application/json"
```

This lists the account's phone numbers without buying a number or sending a message. Treat the returned account data as private. For API-action MCP, the same key authenticates `https://api.telnyx.com/v2/mcp` using streamable HTTP. Documentation search at `https://developers.telnyx.com/mcp` is a separate public service; do not send account credentials to it.

## Errors

* `401 Unauthorized`: check that `Authorization: Bearer` contains the API key, not the temporary session token. Use the discovery hint when returned. Replace an invalid or revoked key rather than repeatedly retrying it.
* `403 Forbidden`: inspect the error for account or permission restrictions. Do not retry unchanged credentials indefinitely.
* `429 Too Many Requests`: follow [rate-limit handling](/docs/development/api-fundamentals/reliability/rate-limiting), including `Retry-After` when supplied. Retry mutations only when the operation's documented retry/idempotency contract permits it.
* API errors use a JSON envelope such as `{"errors": [{"code": "…", "title": "…", "detail": "…"}]}`. Match codes to [API error guidance](/docs/development/api-fundamentals/api-errors) and the [machine-readable catalog](/data/api-errors.json).

## Revocation

Manage API-key revocation through [API Keys in Mission Control Portal](https://portal.telnyx.com/#/app/api-keys); the portal URL is not a protocol revocation endpoint. For routine rotation, create a replacement, update the integration, verify a read-only request, and revoke the old key. Revoke an exposed key promptly. Follow the [credential lifecycle](/docs/development/api-fundamentals/authentication#credential-lifecycle) for operational guidance.