> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gtm-api.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search connected apps

> List the caller's connected apps (standing OAuth consent grants). Always scoped to the caller's own grants, never cross-user. Filter by status (active vs revoked history), oauth_client_sid, or team_scope_mode; include client (name + ceiling), teams (in-scope team names), and active_sessions (live installation tokens). This is the user's view of who has access to their workspaces. page_size:0 returns counts only.

Contract:
- MCP tool `search_oauth_authorizations`, registry package `mcp.id/oauth_authorizations`, mount `id.access`.
- Operation `search`, response envelope `search`.
- Flags: read only.



## OpenAPI

````yaml /api-reference/id/openapi.yaml post /api/oauth-authorizations/search
openapi: 3.0.3
info:
  title: 'GTM API public contract: gtm.service.id'
  description: >-
    Identity, access and money: users, teams and members, API keys, OAuth
    clients and authorizations, billing products, subscriptions, transactions
    and payment methods, the credit ledger, notifications, TLS certificates,
    observability and support requests.


    GENERATED. This document is projected from the Zod MCP tool registry in
    `product/mcp/gtm.mcp` (one tool per public endpoint, 1:1). Do not edit it by
    hand; edit the tool definition and regenerate with `pnpm openapi:public`.


    Surface: the public `/api` contract of `gtm.service.id`, 77 operations.
    Internal (`/internal`) and health endpoints are deliberately absent; the
    code-faithful spec that documents those lives in
    `product/openapi/gtm.openapi.tech`.


    Conventions:

    - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header.

    - Every success body is an MCP envelope: `success: true` plus one typed
    `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`,
    `group_by`, `action`), and a `meta` block with `trace_id` for support.

    - Every failure is the same `McpError` envelope with a code from a fixed
    16-code taxonomy, so a client maps errors once.

    - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward
    `cursor`; `page_size: 0` returns counts only.

    - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`)
    travel as JSON text and array-valued ones repeat as `name[]=value`.

    - The MCP-only `_meta` field (usage analytics) never reaches the backend and
    is not part of this contract.
  version: '1.0'
  contact:
    name: GTM API
    url: https://gtm-api.com
    email: support@gtm-api.com
  license:
    name: Proprietary
    url: https://gtm-api.com/license
servers:
  - url: https://app.gtm-api.com/id/v4
    description: Production, through the app.gtm-api.com gateway
  - url: http://localhost:8021
    description: Local Docker (gtm_id_nginx_dev)
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: account_shares
    description: Registry package `mcp.id/account_shares`, served on MCP mount `id.access`.
  - name: api_keys
    description: Registry package `mcp.id/api_keys`, served on MCP mount `id.access`.
  - name: billing_payment_methods
    description: >-
      Registry package `mcp.id/billing_payment_methods`, served on MCP mount
      `id.billing`.
  - name: billing_products
    description: >-
      Registry package `mcp.id/billing_products`, served on MCP mount
      `id.billing`.
  - name: billing_subscriptions
    description: >-
      Registry package `mcp.id/billing_subscriptions`, served on MCP mount
      `id.billing`.
  - name: billing_transactions
    description: >-
      Registry package `mcp.id/billing_transactions`, served on MCP mount
      `id.billing`.
  - name: credit_transactions
    description: >-
      Registry package `mcp.id/credit_transactions`, served on MCP mount
      `id.credits`.
  - name: notifications
    description: >-
      Registry package `mcp.id/notifications`, served on MCP mount
      `id.platform`.
  - name: oauth_authorizations
    description: >-
      Registry package `mcp.id/oauth_authorizations`, served on MCP mount
      `id.access`.
  - name: oauth_clients
    description: Registry package `mcp.id/oauth_clients`, served on MCP mount `id.access`.
  - name: observability_requests
    description: >-
      Registry package `mcp.id/observability_requests`, served on MCP mount
      `id.platform`.
  - name: sessions
    description: Registry package `mcp.id/sessions`, served on MCP mount `id.identity`.
  - name: ssl_certificates
    description: >-
      Registry package `mcp.id/ssl_certificates`, served on MCP mount
      `id.platform`.
  - name: support_requests
    description: >-
      Registry package `mcp.id/support_requests`, served on MCP mount
      `id.platform`.
  - name: team_members
    description: Registry package `mcp.id/team_members`, served on MCP mount `id.identity`.
  - name: teams
    description: Registry package `mcp.id/teams`, served on MCP mount `id.identity`.
  - name: users
    description: Registry package `mcp.id/users`, served on MCP mount `id.identity`.
paths:
  /api/oauth-authorizations/search:
    post:
      tags:
        - oauth_authorizations
      summary: Search connected apps
      description: >-
        List the caller's connected apps (standing OAuth consent grants). Always
        scoped to the caller's own grants, never cross-user. Filter by status
        (active vs revoked history), oauth_client_sid, or team_scope_mode;
        include client (name + ceiling), teams (in-scope team names), and
        active_sessions (live installation tokens). This is the user's view of
        who has access to their workspaces. page_size:0 returns counts only.


        Contract:

        - MCP tool `search_oauth_authorizations`, registry package
        `mcp.id/oauth_authorizations`, mount `id.access`.

        - Operation `search`, response envelope `search`.

        - Flags: read only.
      operationId: search_oauth_authorizations
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchOauthAuthorizationsRequest'
      responses:
        '200':
          description: '`search` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchOauthAuthorizationsResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    SearchOauthAuthorizationsRequest:
      type: object
      description: Request body of `search_oauth_authorizations`.
      properties:
        filter:
          type: object
          properties:
            oauth_client_sid:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
              description: Filter to one connected client.
            status:
              type: object
              properties:
                eq:
                  type: string
                  enum:
                    - active
                    - revoked
                in:
                  type: array
                  items:
                    type: string
                    enum:
                      - active
                      - revoked
              additionalProperties: false
              description: active vs revoked (history).
            team_scope_mode:
              type: object
              properties:
                eq:
                  type: string
                  enum:
                    - selected
                    - all_my_teams
              additionalProperties: false
              description: Which grants are all_my_teams vs selected.
            created_at:
              type: object
              properties:
                gte:
                  type: string
                lte:
                  type: string
              additionalProperties: false
              description: Connected-since window.
            last_used_at:
              type: object
              properties:
                gte:
                  type: string
                lte:
                  type: string
                is_null:
                  type: boolean
              additionalProperties: false
              description: is_null:true = never used; range = recently active.
        include:
          type: array
          items:
            type: string
            enum:
              - client
              - teams
              - active_sessions
          description: Relations to eager-load (see entity Includes).
        sort:
          type: object
          properties:
            field:
              type: string
              enum:
                - created_at
                - last_used_at
            direction:
              type: string
              enum:
                - asc
                - desc
              description: Default desc.
          required:
            - field
        page_size:
          type: integer
          minimum: 0
          maximum: 500
          description: >-
            0..500, default 50. page_size=0 = count-only, page_size=1 =
            getFirst.
        cursor:
          type: string
          nullable: true
          description: >-
            Opaque forward cursor from a previous response
            pagination.next_cursor.
    SearchOauthAuthorizationsResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - search
        items:
          type: array
          items:
            type: object
            properties:
              item:
                type: object
                properties:
                  sid:
                    type: string
                  user_sid:
                    type: string
                  oauth_client_sid:
                    type: string
                  team_scope_mode:
                    type: string
                    enum:
                      - selected
                      - all_my_teams
                  consented_team_sids:
                    type: array
                    items:
                      type: string
                  permissions:
                    type: array
                    items:
                      type: string
                  status:
                    type: string
                    enum:
                      - active
                      - revoked
                  last_used_at:
                    type: string
                    nullable: true
                  created_at:
                    type: string
                  updated_at:
                    type: string
                required:
                  - sid
                  - user_sid
                  - oauth_client_sid
                  - team_scope_mode
                  - consented_team_sids
                  - permissions
                  - status
                  - last_used_at
                  - created_at
                  - updated_at
              included:
                type: object
                additionalProperties: {}
            required:
              - item
              - included
        pagination:
          type: object
          properties:
            next_cursor:
              type: string
              nullable: true
            has_more:
              type: boolean
            total_count:
              type: integer
              nullable: true
          required:
            - next_cursor
            - has_more
            - total_count
        applied_filters:
          type: object
          additionalProperties: {}
        includes:
          type: array
          items:
            type: string
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            debug_url:
              type: string
              description: Deep link to the post-call analysis UI.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
            - debug_url
        counts:
          type: object
          properties:
            total_count:
              type: number
            groups:
              type: object
              additionalProperties: {}
          required:
            - total_count
            - groups
      required:
        - success
        - operation
        - items
        - pagination
        - applied_filters
        - includes
        - meta
    McpError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
                - nothing_to_update
                - not_found
                - relation_not_found
                - invalid_transition
                - limit_exceeded
                - payment_required
                - duplicate_rejected
                - conflict
                - delete_blocked
                - unauthorized
                - forbidden
                - rate_limited
                - internal_error
                - service_unavailable
                - not_implemented
            message:
              type: string
            recoverable:
              type: boolean
            suggestion:
              type: string
            field_errors:
              type: object
              additionalProperties:
                type: array
                items:
                  anyOf:
                    - type: string
                    - type: object
                      properties:
                        rule:
                          type: string
                        message:
                          type: string
                      required:
                        - rule
                        - message
            blockers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: >-
                      Machine-readable blocker type (active_flow, pending_tasks,
                      …).
                  severity:
                    type: string
                    enum:
                      - hard
                      - soft
                    description: >-
                      hard = external action required; soft = acknowledge is
                      enough.
                  description:
                    type: string
                  entity_sid:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  resolution:
                    type: string
                    description: 'Hard: tool name to call. Soft: code for acknowledge[].'
                  resolution_hint:
                    type: string
                required:
                  - type
                  - severity
                  - description
                  - entity_sid
                  - resolution
                  - resolution_hint
            context:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
            - recoverable
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            debug_url:
              type: string
              description: Deep link to the post-call analysis UI.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
            - debug_url
      required:
        - success
        - error
  responses:
    McpClientError:
      description: >-
        MCP error envelope. `error.code` is one of validation_failed,
        nothing_to_update, not_found, relation_not_found, invalid_transition,
        limit_exceeded, payment_required, duplicate_rejected, conflict,
        delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
    McpServerError:
      description: >-
        MCP error envelope with `error.code` internal_error or
        service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token issued by gtm.service.id. Its `access_identity` claim
        carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is
        authoritative.
    TeamSid:
      type: apiKey
      in: header
      name: Team-SID
      description: >-
        Team scope for tokens that do not carry one. Ignored when the token
        already names a team.

````