Telnyx OAuth Clients API

openapi: 3.2.0
info:
  title: Telnyx OAuth Clients API
  version: 2.0.0
  contact:
    email: support@telnyx.com
  x-endpoint-cost: light
  x-refined-note:
  - x-latency-category differs across the merged source definitions and was not carried
  description: 'Operations tagged OAuth Clients across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: OAuth Clients
paths:
  /oauth/clients:
    get:
      operationId: ListOAuthClients
      tags:
      - OAuth Clients
      summary: List OAuth clients
      description: Retrieve a paginated list of OAuth clients for the authenticated user
      parameters:
      - name: page[size]
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Number of results per page
      - name: page[number]
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
        description: Page number
      - name: filter[client_type]
        in: query
        schema:
          type: string
          enum:
          - confidential
          - public
        description: Filter by client type
      - name: filter[verified]
        in: query
        schema:
          type: boolean
        description: Filter by verification status
      - name: filter[allowed_grant_types][contains]
        in: query
        schema:
          type: string
          enum:
          - client_credentials
          - authorization_code
          - refresh_token
        description: Filter by allowed grant type
      - name: filter[name]
        in: query
        schema:
          type: string
        description: Filter by exact client name
      - name: filter[name][contains]
        in: query
        schema:
          type: string
        description: Filter by client name containing text
      - name: filter[client_id]
        in: query
        schema:
          type: string
        description: Filter by client ID
      responses:
        '200':
          description: List of OAuth clients
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthClient'
                  meta:
                    $ref: '#/components/schemas/oauth_PaginationMeta'
              example:
                data:
                - record_type: oauth_client
                  client_id: string
                  name: string
                  org_id: string
                  user_id: string
                  allowed_scopes:
                  - string
                  client_type: public
                  require_pkce: false
                  allowed_grant_types:
                  - client_credentials
                  redirect_uris:
                  - https://example.com
                  created_at: '2024-01-23T18:10:02.574Z'
                  updated_at: '2024-01-23T18:10:02.574Z'
                meta:
                  page_number: 0
                  page_size: 0
                  total_results: 0
                  total_pages: 0
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
      x-latency-category: responsive
    post:
      operationId: CreateOAuthClient
      tags:
      - OAuth Clients
      summary: Create OAuth client
      description: Creates a new OAuth client on your account for authenticating third-party integrations, and returns the created client.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthClientCreateRequest'
      responses:
        '201':
          description: OAuth client created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
              example:
                data:
                  record_type: oauth_client
                  client_id: string
                  name: string
                  org_id: string
                  user_id: string
                  allowed_scopes:
                  - string
                  client_type: public
                  require_pkce: false
                  allowed_grant_types:
                  - client_credentials
                  redirect_uris:
                  - https://example.com
                  created_at: '2024-01-23T18:10:02.574Z'
                  updated_at: '2024-01-23T18:10:02.574Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
      x-latency-category: responsive
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /oauth/clients/{id}:
    delete:
      operationId: DeleteOAuthClient
      tags:
      - OAuth Clients
      summary: Delete OAuth client
      description: Permanently deletes the specified OAuth client from your account.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: OAuth client ID
      responses:
        '204':
          description: OAuth client deleted successfully
        '404':
          description: OAuth client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
              example:
                error: string
                error_description: string
      x-latency-category: responsive
    get:
      operationId: GetOAuthClient
      tags:
      - OAuth Clients
      summary: Get OAuth client
      description: Returns the details of a single OAuth client on your account by its ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: OAuth client ID
      responses:
        '200':
          description: OAuth client details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
              example:
                data:
                  record_type: oauth_client
                  client_id: string
                  name: string
                  org_id: string
                  user_id: string
                  allowed_scopes:
                  - string
                  client_type: public
                  require_pkce: false
                  allowed_grant_types:
                  - client_credentials
                  redirect_uris:
                  - https://example.com
                  created_at: '2024-01-23T18:10:02.574Z'
                  updated_at: '2024-01-23T18:10:02.574Z'
        '404':
          description: OAuth client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
      x-latency-category: responsive
    put:
      operationId: UpdateOAuthClient
      tags:
      - OAuth Clients
      summary: Update OAuth client
      description: Updates the specified OAuth client's configuration and returns the updated client.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: OAuth client ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthClientUpdateRequest'
      responses:
        '200':
          description: OAuth client updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
              example:
                data:
                  record_type: oauth_client
                  client_id: string
                  name: string
                  org_id: string
                  user_id: string
                  allowed_scopes:
                  - string
                  client_type: public
                  require_pkce: false
                  allowed_grant_types:
                  - client_credentials
                  redirect_uris:
                  - https://example.com
                  created_at: '2024-01-23T18:10:02.574Z'
                  updated_at: '2024-01-23T18:10:02.574Z'
        '404':
          description: OAuth client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_Error'
      x-latency-category: responsive
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /oauth_clients:
    get:
      operationId: ListOAuthClients_2
      tags:
      - OAuth Clients
      summary: List OAuth clients
      description: Retrieve a paginated list of OAuth clients for the authenticated user
      parameters:
      - name: page[size]
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Number of results per page
      - name: page[number]
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
        description: Page number
      - name: filter[client_type]
        in: query
        schema:
          type: string
          enum:
          - confidential
          - public
        description: Filter by client type
      - name: filter[verified]
        in: query
        schema:
          type: boolean
        description: Filter by verification status
      - name: filter[allowed_grant_types][contains]
        in: query
        schema:
          type: string
          enum:
          - client_credentials
          - authorization_code
          - refresh_token
        description: Filter by allowed grant type
      - name: filter[name]
        in: query
        schema:
          type: string
        description: Filter by exact client name
      - name: filter[name][contains]
        in: query
        schema:
          type: string
        description: Filter by client name containing text
      - name: filter[client_id]
        in: query
        schema:
          type: string
        description: Filter by client ID
      responses:
        '200':
          description: List of OAuth clients
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthClient'
                  meta:
                    $ref: '#/components/schemas/oauth_oauth_PaginationMeta'
              example:
                data:
                - record_type: oauth_client
                  client_id: string
                  name: string
                  org_id: string
                  user_id: string
                  allowed_scopes:
                  - string
                  client_type: public
                  require_pkce: false
                  allowed_grant_types:
                  - client_credentials
                  redirect_uris:
                  - https://example.com
                  created_at: '2024-01-23T18:10:02.574Z'
                  updated_at: '2024-01-23T18:10:02.574Z'
                meta:
                  page_number: 0
                  page_size: 0
                  total_results: 0
                  total_pages: 0
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_oauth_Error'
    post:
      operationId: CreateOAuthClient_2
      tags:
      - OAuth Clients
      summary: Create OAuth client
      description: Creates a new OAuth client on your account for authenticating third-party integrations, and returns the created client.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthClientCreateRequest'
      responses:
        '201':
          description: OAuth client created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
              example:
                data:
                  record_type: oauth_client
                  client_id: string
                  name: string
                  org_id: string
                  user_id: string
                  allowed_scopes:
                  - string
                  client_type: public
                  require_pkce: false
                  allowed_grant_types:
                  - client_credentials
                  redirect_uris:
                  - https://example.com
                  created_at: '2024-01-23T18:10:02.574Z'
                  updated_at: '2024-01-23T18:10:02.574Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_oauth_Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_oauth_Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_oauth_Error'
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /oauth_clients/{id}:
    delete:
      operationId: DeleteOAuthClient_2
      tags:
      - OAuth Clients
      summary: Delete OAuth client
      description: Permanently deletes the specified OAuth client from your account.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: OAuth client ID
      responses:
        '204':
          description: OAuth client deleted successfully
        '404':
          description: OAuth client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_oauth_Error'
              example:
                error: string
                error_description: string
    get:
      operationId: GetOAuthClient_2
      tags:
      - OAuth Clients
      summary: Get OAuth client
      description: Returns the details of a single OAuth client on your account by its ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: OAuth client ID
      responses:
        '200':
          description: OAuth client details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
              example:
                data:
                  record_type: oauth_client
                  client_id: string
                  name: string
                  org_id: string
                  user_id: string
                  allowed_scopes:
                  - string
                  client_type: public
                  require_pkce: false
                  allowed_grant_types:
                  - client_credentials
                  redirect_uris:
                  - https://example.com
                  created_at: '2024-01-23T18:10:02.574Z'
                  updated_at: '2024-01-23T18:10:02.574Z'
        '404':
          description: OAuth client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_oauth_Error'
    put:
      operationId: UpdateOAuthClient_2
      tags:
      - OAuth Clients
      summary: Update OAuth client
      description: Updates the specified OAuth client's configuration and returns the updated client.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: OAuth client ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthClientUpdateRequest'
      responses:
        '200':
          description: OAuth client updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
              example:
                data:
                  record_type: oauth_client
                  client_id: string
                  name: string
                  org_id: string
                  user_id: string
                  allowed_scopes:
                  - string
                  client_type: public
                  require_pkce: false
                  allowed_grant_types:
                  - client_credentials
                  redirect_uris:
                  - https://example.com
                  created_at: '2024-01-23T18:10:02.574Z'
                  updated_at: '2024-01-23T18:10:02.574Z'
        '404':
          description: OAuth client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_oauth_Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oauth_oauth_Error'
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
components:
  schemas:
    OAuthClientCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the OAuth client
          example: My OAuth client
        allowed_scopes:
          type: array
          items:
            type: string
          description: List of allowed OAuth scopes
          example:
          - admin
        client_type:
          type: string
          enum:
          - public
          - confidential
          description: OAuth client type
        require_pkce:
          type: boolean
          description: Whether PKCE (Proof Key for Code Exchange) is required for this client
          default: false
        allowed_grant_types:
          type: array
          items:
            type: string
            enum:
            - client_credentials
            - authorization_code
            - refresh_token
          description: List of allowed OAuth grant types
        redirect_uris:
          type: array
          items:
            type: string
            format: uri
          description: List of redirect URIs (required for authorization_code flow)
          default: []
        logo_uri:
          type: string
          format: uri
          description: URL of the client logo
        policy_uri:
          type: string
          format: uri
          description: URL of the client's privacy policy
        tos_uri:
          type: string
          format: uri
          description: URL of the client's terms of service
      required:
      - name
      - allowed_scopes
      - client_type
      - allowed_grant_types
      additionalProperties: false
    OAuthClientUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the OAuth client
        allowed_scopes:
          type: array
          items:
            type: string
          description: List of allowed OAuth scopes
          example:
          - admin
        require_pkce:
          type: boolean
          description: Whether PKCE (Proof Key for Code Exchange) is required for this client
        allowed_grant_types:
          type: array
          items:
            type: string
            enum:
            - client_credentials
            - authorization_code
            - refresh_token
          description: List of allowed OAuth grant types
        redirect_uris:
          type: array
          items:
            type: string
            format: uri
          description: List of redirect URIs
        logo_uri:
          type: string
          format: uri
          description: URL of the client logo
        policy_uri:
          type: string
          format: uri
          description: URL of the client's privacy policy
        tos_uri:
          type: string
          format: uri
          description: URL of the client's terms of service
      additionalProperties: false
    oauth_oauth_Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
        error_description:
          type: string
          description: Human-readable error description
      required:
      - error
    OAuthClient:
      type: object
      properties:
        record_type:
          type: string
          enum:
          - oauth_client
          description: Record type identifier
        client_id:
          type: string
          description: OAuth client identifier
        name:
          type: string
          description: Human-readable name for the OAuth client
        org_id:
          type: string
          description: Organization ID that owns this OAuth client
        user_id:
          type: string
          description: User ID that created this OAuth client
        allowed_scopes:
          type: array
          items:
            type: string
          description: List of allowed OAuth scopes
        client_type:
          type: string
          enum:
          - public
          - confidential
          description: OAuth client type
        require_pkce:
          type: boolean
          description: Whether PKCE (Proof Key for Code Exchange) is required for this client
        allowed_grant_types:
          type: array
          items:
            type: string
            enum:
            - client_credentials
            - authorization_code
            - refresh_token
          description: List of allowed OAuth grant types
        redirect_uris:
          type: array
          items:
            type: string
            format: uri
          description: List of allowed redirect URIs
        logo_uri:
          type:
          - string
          - 'null'
          format: uri
          description: URL of the client logo
        tos_uri:
          type:
          - string
          - 'null'
          format: uri
          description: URL of the client's terms of service
        policy_uri:
          type:
          - string
          - 'null'
          format: uri
          description: URL of the client's privacy policy
        client_secret:
          type:
          - string
          - 'null'
          description: Client secret (only included when available, for confidential clients)
        created_at:
          type: string
          format: date-time
          description: Timestamp when the client was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the client was last updated
      required:
      - record_type
      - client_id
      - name
      - org_id
      - user_id
      - client_type
      - require_pkce
      - created_at
      - updated_at
    oauth_oauth_PaginationMeta:
      type: object
      properties:
        page_number:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
        total_results:
          type: integer
          description: Total number of results
        total_pages:
          type: integer
          description: Total number of pages
    oauth_PaginationMeta:
      type: object
      properties:
        page_number:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
        total_results:
          type: integer
          description: Total number of results
        total_pages:
          type: integer
          description: Total number of pages
    oauth_Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
        error_description:
          type: string
          description: Human-readable error description
      required:
      - error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt