openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens OAuth Clients API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- name: OAuth Clients
paths:
  /oauth_clients:
    get:
      description: Retrieve a paginated list of OAuth clients for the authenticated user
      operationId: ListOAuthClients
      parameters:
      - description: Number of results per page
        in: query
        name: page[size]
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - description: Page number
        in: query
        name: page[number]
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Filter by client type
        in: query
        name: filter[client_type]
        schema:
          enum:
          - confidential
          - public
          type: string
      - description: Filter by verification status
        in: query
        name: filter[verified]
        schema:
          type: boolean
      - description: Filter by allowed grant type
        in: query
        name: filter[allowed_grant_types][contains]
        schema:
          enum:
          - client_credentials
          - authorization_code
          - refresh_token
          type: string
      - description: Filter by exact client name
        in: query
        name: filter[name]
        schema:
          type: string
      - description: Filter by client name containing text
        in: query
        name: filter[name][contains]
        schema:
          type: string
      - description: Filter by client ID
        in: query
        name: filter[client_id]
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/OAuthClient'
                    type: array
                  meta:
                    $ref: '#/components/schemas/oauth_PaginationMeta'
                type: object
          description: List of OAuth clients
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
          description: Unauthorized
      security:
      - bearerAuth: []
      summary: List OAuth clients
      tags:
      - OAuth Clients
      x-latency-category: responsive
    post:
      description: Create a new OAuth client
      operationId: CreateOAuthClient
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthClientCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
                type: object
          description: OAuth client created successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
          description: Unauthorized
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
          description: Validation error
      security:
      - bearerAuth: []
      summary: Create OAuth client
      tags:
      - OAuth Clients
      x-latency-category: responsive
  /oauth_clients/{id}:
    delete:
      description: Delete an OAuth client
      operationId: DeleteOAuthClient
      parameters:
      - description: OAuth client ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '204':
          description: OAuth client deleted successfully
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
          description: OAuth client not found
      security:
      - bearerAuth: []
      summary: Delete OAuth client
      tags:
      - OAuth Clients
      x-latency-category: responsive
    get:
      description: Retrieve a single OAuth client by ID
      operationId: GetOAuthClient
      parameters:
      - description: OAuth client ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
                type: object
          description: OAuth client details
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
          description: OAuth client not found
      security:
      - bearerAuth: []
      summary: Get OAuth client
      tags:
      - OAuth Clients
      x-latency-category: responsive
    put:
      description: Update an existing OAuth client
      operationId: UpdateOAuthClient
      parameters:
      - description: OAuth client ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthClientUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
                type: object
          description: OAuth client updated successfully
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
          description: OAuth client not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
          description: Validation error
      security:
      - bearerAuth: []
      summary: Update OAuth client
      tags:
      - OAuth Clients
      x-latency-category: responsive
components:
  schemas:
    OAuthClientUpdateRequest:
      additionalProperties: false
      properties:
        allowed_grant_types:
          description: List of allowed OAuth grant types
          items:
            enum:
            - client_credentials
            - authorization_code
            - refresh_token
            type: string
          type: array
        allowed_scopes:
          description: List of allowed OAuth scopes
          example:
          - admin
          items:
            type: string
          type: array
        logo_uri:
          description: URL of the client logo
          format: uri
          type: string
        name:
          description: The name of the OAuth client
          type: string
        policy_uri:
          description: URL of the client's privacy policy
          format: uri
          type: string
        redirect_uris:
          description: List of redirect URIs
          items:
            format: uri
            type: string
          type: array
        require_pkce:
          description: Whether PKCE (Proof Key for Code Exchange) is required for this client
          type: boolean
        tos_uri:
          description: URL of the client's terms of service
          format: uri
          type: string
      type: object
    OAuthClientCreateRequest:
      additionalProperties: false
      properties:
        allowed_grant_types:
          description: List of allowed OAuth grant types
          items:
            enum:
            - client_credentials
            - authorization_code
            - refresh_token
            type: string
          type: array
        allowed_scopes:
          description: List of allowed OAuth scopes
          example:
          - admin
          items:
            type: string
          type: array
        client_type:
          description: OAuth client type
          enum:
          - public
          - confidential
          type: string
        logo_uri:
          description: URL of the client logo
          format: uri
          type: string
        name:
          description: The name of the OAuth client
          example: My OAuth client
          type: string
        policy_uri:
          description: URL of the client's privacy policy
          format: uri
          type: string
        redirect_uris:
          default: []
          description: List of redirect URIs (required for authorization_code flow)
          items:
            format: uri
            type: string
          type: array
        require_pkce:
          default: false
          description: Whether PKCE (Proof Key for Code Exchange) is required for this client
          type: boolean
        tos_uri:
          description: URL of the client's terms of service
          format: uri
          type: string
      required:
      - name
      - allowed_scopes
      - client_type
      - allowed_grant_types
      type: object
    oauth_PaginationMeta:
      properties:
        page_number:
          description: Current page number
          type: integer
        page_size:
          description: Number of items per page
          type: integer
        total_pages:
          description: Total number of pages
          type: integer
        total_results:
          description: Total number of results
          type: integer
      type: object
    OAuthClient:
      properties:
        allowed_grant_types:
          description: List of allowed OAuth grant types
          items:
            enum:
            - client_credentials
            - authorization_code
            - refresh_token
            type: string
          type: array
        allowed_scopes:
          description: List of allowed OAuth scopes
          items:
            type: string
          type: array
        client_id:
          description: OAuth client identifier
          type: string
        client_secret:
          description: Client secret (only included when available, for confidential clients)
          type:
          - string
          - 'null'
        client_type:
          description: OAuth client type
          enum:
          - public
          - confidential
          type: string
        created_at:
          description: Timestamp when the client was created
          format: date-time
          type: string
        logo_uri:
          description: URL of the client logo
          format: uri
          type:
          - string
          - 'null'
        name:
          description: Human-readable name for the OAuth client
          type: string
        org_id:
          description: Organization ID that owns this OAuth client
          type: string
        policy_uri:
          description: URL of the client's privacy policy
          format: uri
          type:
          - string
          - 'null'
        record_type:
          description: Record type identifier
          enum:
          - oauth_client
          type: string
        redirect_uris:
          description: List of allowed redirect URIs
          items:
            format: uri
            type: string
          type: array
        require_pkce:
          description: Whether PKCE (Proof Key for Code Exchange) is required for this client
          type: boolean
        tos_uri:
          description: URL of the client's terms of service
          format: uri
          type:
          - string
          - 'null'
        updated_at:
          description: Timestamp when the client was last updated
          format: date-time
          type: string
        user_id:
          description: User ID that created this OAuth client
          type: string
      required:
      - record_type
      - client_id
      - name
      - org_id
      - user_id
      - client_type
      - require_pkce
      - created_at
      - updated_at
      type: object
    oauth_Error:
      properties:
        error:
          description: Error code
          type: string
        error_description:
          description: Human-readable error description
          type: string
      required:
      - error
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http