Installation
go get github.com/team-telnyx/telnyx-go
Setup
import (
"context"
"fmt"
"os"
"github.com/team-telnyx/telnyx-go" "github.com/team-telnyx/telnyx-go/option" )
client := telnyx.NewClient( option.WithAPIKey(os.Getenv("TELNYX_API_KEY")), )
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:
```go
import "errors"
result, err := client.Messages.Send(ctx, params)
if err != nil {
var apiErr *telnyx.Error
if errors.As(err, &apiErr) {
switch apiErr.StatusCode {
case 422:
fmt.Println("Validation error — check required fields and formats")
case 429:
// Rate limited — wait and retry with exponential backoff
fmt.Println("Rate limited, retrying...")
default:
fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Error())
}
} else {
fmt.Println("Network error — check connectivity and retry")
}
}
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: Use
ListAutoPaging()for automatic iteration:iter := client.Resource.ListAutoPaging(ctx, params); for iter.Next() { item := iter.Current() }.
Authorization server metadata
OAuth 2.0 Authorization Server Metadata (RFC 8414)
GET /.well-known/oauth-authorization-server
response, err := client.WellKnown.GetAuthorizationServerMetadata(context.Background())
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.AuthorizationEndpoint)
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
response, err := client.WellKnown.GetProtectedResourceMetadata(context.Background())
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.AuthorizationServers)
Returns: authorization_servers (array[string]), resource (uri)
OAuth authorization endpoint
OAuth 2.0 authorization endpoint for the authorization code flow
GET /oauth/authorize
err := client.OAuth.GetAuthorize(context.Background(), telnyx.OAuthGetAuthorizeParams{
ClientID: "550e8400-e29b-41d4-a716-446655440000",
RedirectUri: "https://example.com",
ResponseType: telnyx.OAuthGetAuthorizeParamsResponseTypeCode,
})
if err != nil {
log.Fatal(err)
}
Get OAuth consent token
Retrieve details about an OAuth consent token
GET /oauth/consent/{consent_token}
oauth, err := client.OAuth.Get(context.Background(), "consent_token")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", 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
response, err := client.OAuth.Grants(context.Background(), telnyx.OAuthGrantsParams{
Allowed: true,
ConsentToken: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.example",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.RedirectUri)
Returns: redirect_uri (uri)
Token introspection
Introspect an OAuth access token to check its validity and metadata
POST /oauth/introspect — Required: token
response, err := client.OAuth.Introspect(context.Background(), telnyx.OAuthIntrospectParams{
Token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.example",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.ClientID)
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
response, err := client.OAuth.GetJwks(context.Background())
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", 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)
response, err := client.OAuth.Register(context.Background(), telnyx.OAuthRegisterParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.ClientID)
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)
response, err := client.OAuth.Token(context.Background(), telnyx.OAuthTokenParams{
GrantType: telnyx.OAuthTokenParamsGrantTypeClientCredentials,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.AccessToken)
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
page, err := client.OAuthClients.List(context.Background(), telnyx.OAuthClientListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", page)
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)
oauthClient, err := client.OAuthClients.New(context.Background(), telnyx.OAuthClientNewParams{
AllowedGrantTypes: []string{"client_credentials"},
AllowedScopes: []string{"admin"},
ClientType: telnyx.OAuthClientNewParamsClientTypePublic,
Name: "My OAuth client",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", 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}
oauthClient, err := client.OAuthClients.Get(context.Background(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", 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)
oauthClient, err := client.OAuthClients.Update(
context.Background(),
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
telnyx.OAuthClientUpdateParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", 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}
err := client.OAuthClients.Delete(context.Background(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
if err != nil {
log.Fatal(err)
}
List OAuth grants
Retrieve a paginated list of OAuth grants for the authenticated user
GET /oauth_grants
page, err := client.OAuthGrants.List(context.Background(), telnyx.OAuthGrantListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", page)
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}
oauthGrant, err := client.OAuthGrants.Get(context.Background(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", 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}
oauthGrant, err := client.OAuthGrants.Delete(context.Background(), "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", 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])