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" ;;
esacCommon 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]andpage[size]query parameters to navigate pages. Checkmeta.total_pagesin 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])