> ## 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, following the [auth.md convention](https://workos.com/auth-md). It covers the complete lifecycle: discovering how authentication works, registering, claiming a credential, using it, handling errors, and revoking it.

## Discover

* Protected-resource metadata (RFC 9728): [`https://api.telnyx.com/.well-known/oauth-protected-resource`](https://api.telnyx.com/.well-known/oauth-protected-resource) lists the `resource` and `authorization_servers`.
* The API does not currently advertise an `agent_auth` block in authorization-server metadata, and 401 responses do not yet carry a `WWW-Authenticate: Bearer resource_metadata="…"` hint — treat this document as the canonical discovery path.
* Machine-readable context: [llms.txt](https://developers.telnyx.com/llms.txt) · [capabilities](https://telnyx.com/ai/capabilities.json) · [pricing](https://telnyx.com/pricing.md)

## Pick a method

Telnyx uses **Bearer API keys** — one method for every product API. `identity_assertion` flows and `id-jag` token exchange are not offered today; anonymous registration with trial credit is.

## Register

* **register\_uri (programmatic):** [`https://telnyx.com/agent-signup.md`](https://telnyx.com/agent-signup.md) — bot-challenge signup flow designed for agents; an email-verification step applies before the account activates.
* **Interactive:** [sign up](https://telnyx.com/sign-up) (free trial credit, no card required), then manage everything in [Mission Control Portal](https://portal.telnyx.com).

## Claim the credential

* **claim\_uri (interactive):** [`https://portal.telnyx.com/#/app/api-keys`](https://portal.telnyx.com/#/app/api-keys) — create a V2 API key and copy it once at creation time.
* Programmatic claiming follows the agent-signup flow above.

## Use the credential

Send the key as a Bearer token on every request to `https://api.telnyx.com/v2`:

```bash theme={null}
curl https://api.telnyx.com/v2/available_phone_numbers \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

The same key authenticates the MCP server at `https://api.telnyx.com/v2/mcp` (streamable-http transport).

## Errors

* `401 Unauthorized` — missing or invalid key (no `WWW-Authenticate` challenge header is returned today; re-check your `Authorization: Bearer` header)
* `403 Forbidden` — the key is valid but lacks permission for the resource
* Error bodies use a JSON envelope: `{"errors": [{"code": "…", "title": "…", "detail": "…"}]}`

## Revocation

* **revocation\_uri (interactive):** [`https://portal.telnyx.com/#/app/api-keys`](https://portal.telnyx.com/#/app/api-keys) — delete or rotate keys; revocation takes effect immediately.
* Rotate any key that may have been exposed and create scoped replacement keys per integration.