team-telnyx/ai / providers/claude/plugins/telnyx-platform/skills/telnyx-oauth-javascript
telnyx-oauth-javascript
VerifiedImplement OAuth 2.0 authentication flows for Telnyx API access. This skill provides JavaScript SDK examples.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.1 KB |
SKILL.md
View on GitHub---
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-openapi-pipeline
---
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
# Telnyx Oauth - JavaScript
## Installation
```bash
npm install telnyx@6.74.2
```
## Setup
```javascript
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
publicKey: process.env['TELNYX_PUBLIC_KEY'], // Required for client.webhooks.unwrap() (webhook verification)
});
```
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, then retry the request (bounded exponential backoff)
const retryAfter = err.headers?.['retry-after'] || 1;
await new Promise(r => setTimeout(r, retryAfter * 1000));
// ...retry the call here (give up after a few attempts)
} 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');
}
}
throw err; // Re-throw: a failed request must never look like success to the caller
}
```
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
Creates an OAuth authorization grant and returns the grant response for completing the authorization flow.
`POST /oauth/grants` — Required: `allowed`, `consent_token`
```javascript
const response = await client.oauth.grants({ allowed: true, consent_token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.example' });
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
Creates a new OAuth client on your account for authenticating third-party integrations, and returns the created 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
Returns the details of a single OAuth client on your account by its 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
Updates the specified OAuth client's configuration and returns the updated 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
Permanently deletes the specified OAuth client from your account.
`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
Returns the details of a single OAuth grant on your account by its 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
Revokes the specified OAuth grant, withdrawing the access previously granted to the client.
`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])
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |