--- name: telnyx-oauth-javascript description: >- Implement OAuth 2.0 authentication flows for Telnyx API access. This skill provides JavaScript SDK examples. metadata: author: telnyx product: oauth language: javascript generated_by: telnyx-ext-skills-generator --- # Telnyx Oauth - JavaScript ## Installation ```bash npm install telnyx ``` ## Setup ```javascript import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); ``` All examples below assume `client` is already initialized as shown above. ## 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: ```javascript try { const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' }); } catch (err) { if (err instanceof Telnyx.APIConnectionError) { console.error('Network error — check connectivity and retry'); } else if (err instanceof Telnyx.RateLimitError) { // 429: rate limited — wait and retry with exponential backoff const retryAfter = err.headers?.['retry-after'] || 1; await new Promise(r => setTimeout(r, retryAfter * 1000)); } else if (err instanceof Telnyx.APIError) { console.error(`API error ${err.status}: ${err.message}`); if (err.status === 422) { console.error('Validation error — check required fields and formats'); } } } ``` 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 methods return an auto-paginating iterator. Use `for await (const item of result) { ... }` to iterate through all pages automatically. ## Authorization server metadata OAuth 2.0 Authorization Server Metadata (RFC 8414) `GET /.well-known/oauth-authorization-server` ```javascript const response = await client.wellKnown.retrieveAuthorizationServerMetadata(); console.log(response.authorization_endpoint); ``` 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` ```javascript const response = await client.wellKnown.retrieveProtectedResourceMetadata(); console.log(response.authorization_servers); ``` Returns: `authorization_servers` (array[string]), `resource` (uri) ## OAuth authorization endpoint OAuth 2.0 authorization endpoint for the authorization code flow `GET /oauth/authorize` ```javascript await client.oauth.retrieveAuthorize({ client_id: '550e8400-e29b-41d4-a716-446655440000', redirect_uri: 'https://example.com', response_type: 'code', }); ``` ## Get OAuth consent token Retrieve details about an OAuth consent token `GET /oauth/consent/{consent_token}` ```javascript const oauth = await client.oauth.retrieve('consent_token'); console.log(oauth.data); ``` 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` ```javascript const response = await client.oauth.grants({ allowed: true, consent_token: 'consent_token' }); console.log(response.redirect_uri); ``` Returns: `redirect_uri` (uri) ## Token introspection Introspect an OAuth access token to check its validity and metadata `POST /oauth/introspect` — Required: `token` ```javascript const response = await client.oauth.introspect({ token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.example' }); console.log(response.client_id); ``` 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` ```javascript const response = await client.oauth.retrieveJwks(); console.log(response.keys); ``` 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) ```javascript const response = await client.oauth.register(); console.log(response.client_id); ``` 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) ```javascript const response = await client.oauth.token({ grant_type: 'client_credentials' }); console.log(response.access_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` ```javascript // Automatically fetches more pages as needed. for await (const oauthClient of client.oauthClients.list()) { console.log(oauthClient.client_id); } ``` 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) ```javascript const oauthClient = await client.oauthClients.create({ allowed_grant_types: ['client_credentials'], allowed_scopes: ['admin'], client_type: 'public', name: 'My OAuth client', }); console.log(oauthClient.data); ``` 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}` ```javascript const oauthClient = await client.oauthClients.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(oauthClient.data); ``` 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) ```javascript const oauthClient = await client.oauthClients.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(oauthClient.data); ``` 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}` ```javascript await client.oauthClients.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); ``` ## List OAuth grants Retrieve a paginated list of OAuth grants for the authenticated user `GET /oauth_grants` ```javascript // Automatically fetches more pages as needed. for await (const oauthGrant of client.oauthGrants.list()) { console.log(oauthGrant.id); } ``` 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}` ```javascript const oauthGrant = await client.oauthGrants.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(oauthGrant.data); ``` 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}` ```javascript const oauthGrant = await client.oauthGrants.delete('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(oauthGrant.data); ``` Returns: `client_id` (string), `created_at` (date-time), `id` (uuid), `last_used_at` (date-time), `record_type` (enum: oauth_grant), `scopes` (array[string])