<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Oauth - curl

Installation

# curl is pre-installed on macOS, Linux, and Windows 10+

Setup

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

All examples below use

$TELNYX_API_KEY

for authentication.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

# Check HTTP status code in response
response=$(curl -s -w "\n%{http_code}" \
  -X POST "https://api.telnyx.com/v2/messages" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

case $http_code in
  2*) echo "Success: $body" ;;
  422) echo "Validation error — check required fields and formats" ;;
  429) echo "Rate limited — retry after delay"; sleep 1 ;;
  401) echo "Authentication failed — check TELNYX_API_KEY" ;;
  *)   echo "Error $http_code: $body" ;;
esac

Common error codes:

401

invalid API key,

403

insufficient permissions,

404

resource not found,

422

validation error (check field formats),

429

rate limited (retry with exponential backoff).

Important Notes

• Pagination: List endpoints return paginated results. Use

  page[number]

  and

  page[size]

  query parameters to navigate pages. Check

  meta.total_pages

  in the response.

Authorization server metadata

OAuth 2.0 Authorization Server Metadata (RFC 8414)

GET /.well-known/oauth-authorization-server

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/.well-known/oauth-authorization-server"

Returns:

authorization_endpoint

(uri),

code_challenge_methods_supported

(array[string]),

grant_types_supported

(array[string]),

introspection_endpoint

(uri),

issuer

(uri),

jwks_uri

(uri),

registration_endpoint

(uri),

response_types_supported

(array[string]),

scopes_supported

(array[string]),

token_endpoint

(uri),

token_endpoint_auth_methods_supported

(array[string])

Protected resource metadata

OAuth 2.0 Protected Resource Metadata for resource discovery

GET /.well-known/oauth-protected-resource

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/.well-known/oauth-protected-resource"

Returns:

authorization_servers

(array[string]),

resource

(uri)

OAuth authorization endpoint

OAuth 2.0 authorization endpoint for the authorization code flow

GET /oauth/authorize

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/oauth/authorize?scope=admin"

Get OAuth consent token

Retrieve details about an OAuth consent token

GET /oauth/consent/{consent_token}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/oauth/consent/{consent_token}"

Returns:

client_id

(string),

logo_uri

(uri),

name

(string),

policy_uri

(uri),

redirect_uri

(uri),

requested_scopes

(array[object]),

tos_uri

(uri),

verified

(boolean)

Create OAuth grant

Create an OAuth authorization grant

POST /oauth/grants

— Required:

allowed

,

consent_token

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "allowed": true,
  "consent_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.example"
}' \
  "https://api.telnyx.com/v2/oauth/grants"

Returns:

redirect_uri

(uri)

Token introspection

Introspect an OAuth access token to check its validity and metadata

POST /oauth/introspect

— Required:

token

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.example"
}' \
  "https://api.telnyx.com/v2/oauth/introspect"

Returns:

active

(boolean),

aud

(string),

client_id

(string),

exp

(integer),

iat

(integer),

iss

(string),

scope

(string)

JSON Web Key Set

Retrieve the JSON Web Key Set for token verification

GET /oauth/jwks

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/oauth/jwks"

Returns:

keys

(array[object])

Dynamic client registration

Register a new OAuth client dynamically (RFC 7591)

POST /oauth/register

Optional:

client_name

(string),

grant_types

(array[string]),

logo_uri

(uri),

policy_uri

(uri),

redirect_uris

(array[string]),

response_types

(array[string]),

scope

(string),

token_endpoint_auth_method

(enum: none, client_secret_basic, client_secret_post),

tos_uri

(uri)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/oauth/register"

Returns:

client_id

(string),

client_id_issued_at

(integer),

client_name

(string),

client_secret

(string),

grant_types

(array[string]),

logo_uri

(uri),

policy_uri

(uri),

redirect_uris

(array[string]),

response_types

(array[string]),

scope

(string),

token_endpoint_auth_method

(string),

tos_uri

(uri)

OAuth token endpoint

Exchange authorization code, client credentials, or refresh token for access token

POST /oauth/token

— Required:

grant_type

Optional:

client_id

(string),

client_secret

(string),

code

(string),

code_verifier

(string),

redirect_uri

(uri),

refresh_token

(string),

scope

(string)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "grant_type": "client_credentials"
}' \
  "https://api.telnyx.com/v2/oauth/token"

Returns:

access_token

(string),

expires_in

(integer),

refresh_token

(string),

scope

(string),

token_type

(enum: Bearer)

List OAuth clients

Retrieve a paginated list of OAuth clients for the authenticated user

GET /oauth_clients

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/oauth_clients"

Returns:

allowed_grant_types

(array[string]),

allowed_scopes

(array[string]),

client_id

(string),

client_secret

(string | null),

client_type

(enum: public, confidential),

created_at

(date-time),

logo_uri

(uri),

name

(string),

org_id

(string),

policy_uri

(uri),

record_type

(enum: oauth_client),

redirect_uris

(array[string]),

require_pkce

(boolean),

tos_uri

(uri),

updated_at

(date-time),

user_id

(string)

Create OAuth client

Create a new OAuth client

POST /oauth_clients

— Required:

name

,

allowed_scopes

,

client_type

,

allowed_grant_types

Optional:

logo_uri

(uri),

policy_uri

(uri),

redirect_uris

(array[string]),

require_pkce

(boolean),

tos_uri

(uri)

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My OAuth client",
  "allowed_scopes": [
    "admin"
  ],
  "client_type": "public",
  "allowed_grant_types": [
    "client_credentials"
  ]
}' \
  "https://api.telnyx.com/v2/oauth_clients"

Returns:

allowed_grant_types

(array[string]),

allowed_scopes

(array[string]),

client_id

(string),

client_secret

(string | null),

client_type

(enum: public, confidential),

created_at

(date-time),

logo_uri

(uri),

name

(string),

org_id

(string),

policy_uri

(uri),

record_type

(enum: oauth_client),

redirect_uris

(array[string]),

require_pkce

(boolean),

tos_uri

(uri),

updated_at

(date-time),

user_id

(string)

Get OAuth client

Retrieve a single OAuth client by ID

GET /oauth_clients/{id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/oauth_clients/550e8400-e29b-41d4-a716-446655440000"

Returns:

allowed_grant_types

(array[string]),

allowed_scopes

(array[string]),

client_id

(string),

client_secret

(string | null),

client_type

(enum: public, confidential),

created_at

(date-time),

logo_uri

(uri),

name

(string),

org_id

(string),

policy_uri

(uri),

record_type

(enum: oauth_client),

redirect_uris

(array[string]),

require_pkce

(boolean),

tos_uri

(uri),

updated_at

(date-time),

user_id

(string)

Update OAuth client

Update an existing OAuth client

PUT /oauth_clients/{id}

Optional:

allowed_grant_types

(array[string]),

allowed_scopes

(array[string]),

logo_uri

(uri),

name

(string),

policy_uri

(uri),

redirect_uris

(array[string]),

require_pkce

(boolean),

tos_uri

(uri)

curl \
  -X PUT \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/oauth_clients/550e8400-e29b-41d4-a716-446655440000"

Returns:

allowed_grant_types

(array[string]),

allowed_scopes

(array[string]),

client_id

(string),

client_secret

(string | null),

client_type

(enum: public, confidential),

created_at

(date-time),

logo_uri

(uri),

name

(string),

org_id

(string),

policy_uri

(uri),

record_type

(enum: oauth_client),

redirect_uris

(array[string]),

require_pkce

(boolean),

tos_uri

(uri),

updated_at

(date-time),

user_id

(string)

Delete OAuth client

Delete an OAuth client

DELETE /oauth_clients/{id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/oauth_clients/550e8400-e29b-41d4-a716-446655440000"

List OAuth grants

Retrieve a paginated list of OAuth grants for the authenticated user

GET /oauth_grants

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/oauth_grants"

Returns:

client_id

(string),

created_at

(date-time),

id

(uuid),

last_used_at

(date-time),

record_type

(enum: oauth_grant),

scopes

(array[string])

Get OAuth grant

Retrieve a single OAuth grant by ID

GET /oauth_grants/{id}

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/oauth_grants/550e8400-e29b-41d4-a716-446655440000"

Returns:

client_id

(string),

created_at

(date-time),

id

(uuid),

last_used_at

(date-time),

record_type

(enum: oauth_grant),

scopes

(array[string])

Revoke OAuth grant

Revoke an OAuth grant

DELETE /oauth_grants/{id}

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/oauth_grants/550e8400-e29b-41d4-a716-446655440000"

Returns:

client_id

(string),

created_at

(date-time),

id

(uuid),

last_used_at

(date-time),

record_type

(enum: oauth_grant),

scopes

(array[string])