openapi: 3.2.0
info:
  description: The One API. Universal API integration platform for AI agents and applications.
  license:
    name: ''
  title: One OAuth Clients API
  version: 5.35.0
tags:
- name: OAuth Clients
paths:
  /v1/oauth-clients:
    get:
      operationId: list_oauth_clients
      parameters:
      - description: 'Items per page. Default 20, hard-capped at 150. `limit=0` is

          treated as 1. Larger values silently clamp.'
        example: 20
        in: query
        name: limit
        required: false
        schema:
          default: 20
          format: int64
          maximum: 150
          minimum: 0
          type: integer
      - description: Page number for pagination (1-indexed). Defaults to 1.
        example: 1
        in: query
        name: page
        required: false
        schema:
          default: 1
          format: int64
          minimum: 0
          type: integer
      - description: 'Number of items to skip before the first returned item. Defaults to 0.

          Most callers should leave this at 0 and rely on `page` + `limit`.'
        example: 0
        in: query
        name: skip
        required: false
        schema:
          default: 0
          format: int64
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated_OAuthClientView'
          description: OAuth clients owned by the caller
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: List oauth clients
      x-summary-source: derived
    post:
      operationId: create_oauth_client
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateParams'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientCreatedView'
          description: OAuth client created; the plain secret is shown once
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Create oauth client
      x-summary-source: derived
  /v1/oauth-clients/{client_id}:
    delete:
      operationId: delete_oauth_client
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OAuth client deleted
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Delete oauth client
      x-summary-source: derived
    get:
      operationId: retrieve_oauth_client
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientView'
          description: OAuth client details
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Retrieve oauth client
      x-summary-source: derived
    patch:
      operationId: update_oauth_client
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateParams'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientView'
          description: OAuth client updated
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Update oauth client
      x-summary-source: derived
  /v1/oauth-clients/{client_id}/permission-sets:
    get:
      operationId: list_permission_sets
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      - description: 'Items per page. Default 20, hard-capped at 150. `limit=0` is

          treated as 1. Larger values silently clamp.'
        example: 20
        in: query
        name: limit
        required: false
        schema:
          default: 20
          format: int64
          maximum: 150
          minimum: 0
          type: integer
      - description: Page number for pagination (1-indexed). Defaults to 1.
        example: 1
        in: query
        name: page
        required: false
        schema:
          default: 1
          format: int64
          minimum: 0
          type: integer
      - description: 'Number of items to skip before the first returned item. Defaults to 0.

          Most callers should leave this at 0 and rely on `page` + `limit`.'
        example: 0
        in: query
        name: skip
        required: false
        schema:
          default: 0
          format: int64
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated_OAuthPermissionSetView'
          description: The client's permission sets, without connector resolution
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: List permission sets
      x-summary-source: derived
    post:
      operationId: create_permission_set
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionSetBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionSetDetailView'
          description: Permission set created, with its connectors resolved
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Create permission set
      x-summary-source: derived
  /v1/oauth-clients/{client_id}/permission-sets/{id}:
    delete:
      operationId: delete_permission_set
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      - description: Permission set ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: Permission set retired; grants already made are untouched
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Delete permission set
      x-summary-source: derived
    get:
      operationId: retrieve_permission_set
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      - description: Permission set ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionSetDetailView'
          description: Permission set with its connectors resolved
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Retrieve permission set
      x-summary-source: derived
    patch:
      operationId: update_permission_set
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      - description: Permission set ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionSetBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionSetDetailView'
          description: Permission set updated, with its connectors resolved; grants already made are untouched
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Update permission set
      x-summary-source: derived
  /v1/oauth-clients/{client_id}/secret:
    post:
      operationId: regenerate_oauth_client_secret
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretView'
          description: New client secret; shown once and never recoverable
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Regenerate oauth client secret
      x-summary-source: derived
  /v1/oauth-clients/{client_id}/users:
    get:
      operationId: list_oauth_client_users
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      - description: 'Items per page. Default 20, hard-capped at 150. `limit=0` is

          treated as 1. Larger values silently clamp.'
        example: 20
        in: query
        name: limit
        required: false
        schema:
          default: 20
          format: int64
          maximum: 150
          minimum: 0
          type: integer
      - description: Page number for pagination (1-indexed). Defaults to 1.
        example: 1
        in: query
        name: page
        required: false
        schema:
          default: 1
          format: int64
          minimum: 0
          type: integer
      - description: 'Number of items to skip before the first returned item. Defaults to 0.

          Most callers should leave this at 0 and rely on `page` + `limit`.'
        example: 0
        in: query
        name: skip
        required: false
        schema:
          default: 0
          format: int64
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated_ClientUserView'
          description: Users who authorized this client
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: List oauth client users
      x-summary-source: derived
  /v1/oauth-clients/{client_id}/users/{user_id}:
    delete:
      operationId: revoke_oauth_client_user
      parameters:
      - description: Public OAuth client ID
        in: path
        name: client_id
        required: true
        schema:
          type: string
      - description: User whose access is revoked
        in: path
        name: user_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthRevokeAuthorizationResponse'
          description: Tokens revoked
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - OAuth Clients
      summary: Revoke oauth client user
      x-summary-source: derived
components:
  schemas:
    ErrorResponse:
      properties:
        correlationId:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        key:
          example: http_error
          type: string
        message:
          example: Authentication required
          type: string
        status:
          example: 401
          format: int32
          minimum: 0
          type: integer
        type:
          example: http_error
          type: string
      required:
      - correlationId
      - key
      - message
      - type
      - status
      type: object
    OAuthRevokeAuthorizationResponse:
      properties:
        accessTokens:
          format: int64
          minimum: 0
          type: integer
        refreshTokens:
          format: int64
          minimum: 0
          type: integer
        success:
          type: boolean
      required:
      - success
      - accessTokens
      - refreshTokens
      type: object
    OAuthClientId:
      description: Prefixed ID with 'oac' prefix (e.g., 'oac_1C'), also accepts raw integer
      type: string
    Paginated_OAuthPermissionSetView:
      properties:
        page:
          format: int64
          minimum: 0
          type: integer
        pages:
          format: int64
          minimum: 0
          type: integer
        rows:
          items:
            description: 'The wire shape of a permission set.


              Lives here rather than beside the entity in `common`: it is the response

              contract of core''s `/v1/oauth-clients` routes and would make no sense

              without them, and a shared crate holds no one consumer''s vocabulary. The

              entity and its store stay in `common`, where any service could reuse them.'
            properties:
              active:
                type: boolean
              clientId:
                description: 'The owning client''s public `client_id`, not the integer key: the key is

                  internal and the caller addresses the client by the string everywhere

                  else in `/v1/oauth-clients`.'
                type: string
              connectorRules:
                description: 'The connectors this set grants, or `null` for the **allow-all** set,

                  which grants every connector exactly as a ceremony naming no set does.

                  The same shape create accepts, so a fetched set round-trips.'
                items:
                  $ref: '#/components/schemas/ConnectorRule'
                type:
                - array
                - 'null'
              createdAt:
                format: date-time
                type: string
              id:
                format: uuid
                type: string
              name:
                type: string
              updatedAt:
                format: date-time
                type: string
            required:
            - id
            - clientId
            - name
            - createdAt
            - updatedAt
            - active
            type: object
          type: array
        total:
          format: int64
          minimum: 0
          type: integer
      required:
      - rows
      - total
      - pages
      - page
      type: object
    UpdateParams:
      properties:
        accessTokenTtl:
          description: Access-token lifetime in seconds, one of the offered choices; any other value is refused. Omit to leave the current lifetime unchanged - there is no way to clear it back to the platform default once set.
          enum:
          - 604800
          - 2592000
          - 7776000
          - 31536000
          - null
          format: int32
          type:
          - integer
          - 'null'
        consentSurface:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ConsentSurface'
            description: 'Where this client''s users grant consent. Omitting it leaves the current

              surface alone, like every other field here.'
        description:
          type:
          - string
          - 'null'
        homepageUrl:
          type:
          - string
          - 'null'
        isActive:
          type:
          - boolean
          - 'null'
        logoUrl:
          type:
          - string
          - 'null'
        name:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/NonEmptyString'
        redirectUris:
          items:
            $ref: '#/components/schemas/NonEmptyString'
          type:
          - array
          - 'null'
      type: object
    ConsentSurface:
      description: 'Where an OAuth client''s users are sent to grant consent.


        The surface used to be read off the client id, so a client could only get a

        different one by being renamed, and every existing client would have moved

        the moment the rule changed. Naming it on the row makes it a property of the

        client that its owner can see and set, and leaves the ones already running

        exactly where they are.'
      enum:
      - hosted
      - connect
      type: string
    NonEmptyString:
      type: string
    OAuthPermissionSetView:
      description: 'The wire shape of a permission set.


        Lives here rather than beside the entity in `common`: it is the response

        contract of core''s `/v1/oauth-clients` routes and would make no sense

        without them, and a shared crate holds no one consumer''s vocabulary. The

        entity and its store stay in `common`, where any service could reuse them.'
      properties:
        active:
          type: boolean
        clientId:
          description: 'The owning client''s public `client_id`, not the integer key: the key is

            internal and the caller addresses the client by the string everywhere

            else in `/v1/oauth-clients`.'
          type: string
        connectorRules:
          description: 'The connectors this set grants, or `null` for the **allow-all** set,

            which grants every connector exactly as a ceremony naming no set does.

            The same shape create accepts, so a fetched set round-trips.'
          items:
            $ref: '#/components/schemas/ConnectorRule'
          type:
          - array
          - 'null'
        createdAt:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        name:
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
      - id
      - clientId
      - name
      - createdAt
      - updatedAt
      - active
      type: object
    Paginated_OAuthClientView:
      properties:
        page:
          format: int64
          minimum: 0
          type: integer
        pages:
          format: int64
          minimum: 0
          type: integer
        rows:
          items:
            properties:
              accessTokenTtl:
                format: int32
                type:
                - integer
                - 'null'
              clientId:
                type: string
              clientType:
                type: string
              consentSurface:
                $ref: '#/components/schemas/ConsentSurface'
              createdAt:
                format: date-time
                type: string
              description:
                type:
                - string
                - 'null'
              grantTypes:
                items:
                  type: string
                type: array
              homepageUrl:
                type:
                - string
                - 'null'
              id:
                $ref: '#/components/schemas/OAuthClientId'
              isActive:
                type: boolean
              logoUrl:
                type:
                - string
                - 'null'
              name:
                type: string
              ownerId:
                format: uuid
                type: string
              redirectUris:
                items:
                  type: string
                type: array
              updatedAt:
                format: date-time
                type: string
            required:
            - id
            - clientId
            - name
            - redirectUris
            - clientType
            - grantTypes
            - ownerId
            - isActive
            - consentSurface
            - createdAt
            - updatedAt
            type: object
          type: array
        total:
          format: int64
          minimum: 0
          type: integer
      required:
      - rows
      - total
      - pages
      - page
      type: object
    SecretView:
      properties:
        clientId:
          type: string
        clientSecret:
          type: string
      required:
      - clientId
      - clientSecret
      type: object
    OAuthClientView:
      properties:
        accessTokenTtl:
          format: int32
          type:
          - integer
          - 'null'
        clientId:
          type: string
        clientType:
          type: string
        consentSurface:
          $ref: '#/components/schemas/ConsentSurface'
        createdAt:
          format: date-time
          type: string
        description:
          type:
          - string
          - 'null'
        grantTypes:
          items:
            type: string
          type: array
        homepageUrl:
          type:
          - string
          - 'null'
        id:
          $ref: '#/components/schemas/OAuthClientId'
        isActive:
          type: boolean
        logoUrl:
          type:
          - string
          - 'null'
        name:
          type: string
        ownerId:
          format: uuid
          type: string
        redirectUris:
          items:
            type: string
          type: array
        updatedAt:
          format: date-time
          type: string
      required:
      - id
      - clientId
      - name
      - redirectUris
      - clientType
      - grantTypes
      - ownerId
      - isActive
      - consentSurface
      - createdAt
      - updatedAt
      type: object
    GrantedConnectorView:
      description: 'One connector an issued grant reaches, as an audit surface reports it.


        **Not [`ResolvedConnectorView`].** This is a read-only report, never fed

        back into a request: a dashboard folds every live token together, and the

        envelopes of several grants on one connector do not combine into one, so a

        rule-shaped answer here would be a rule nobody granted.'
      properties:
        actionCount:
          description: 'Distinct actions reached across every grant and connection touching

            this connector - the union, so a shared action counts once and disjoint

            ones each.'
          minimum: 0
          type: integer
        connectionCount:
          description: 'Distinct connections the grants name here. `None` when one of them

            named the *connector*, which reaches every connection on it including

            ones added later, so no count would be true for long.'
          minimum: 0
          type:
          - integer
          - 'null'
        connectionDefinitionId:
          $ref: '#/components/schemas/ConnectionDefinitionId'
        imageUrl:
          type: string
        name:
          type: string
        platform:
          type: string
      required:
      - connectionDefinitionId
      - name
      - platform
      - imageUrl
      - actionCount
      type: object
    ResolvedConnectorView:
      allOf:
      - $ref: '#/components/schemas/EnvelopeView'
      - properties:
          actionCount:
            minimum: 0
            type: integer
          connectionDefinitionId:
            $ref: '#/components/schemas/ConnectionDefinitionId'
          imageUrl:
            type: string
          name:
            type: string
          platform:
            type: string
        required:
        - connectionDefinitionId
        - name
        - platform
        - imageUrl
        - actionCount
        type: object
    PermissionSetDetailView:
      allOf:
      - $ref: '#/components/schemas/OAuthPermissionSetView'
      - properties:
          connectors:
            items:
              $ref: '#/components/schemas/ResolvedConnectorView'
            type: array
        required:
        - connectors
        type: object
      description: 'A set plus its rules resolved against the connector catalog.


        Resolution is offered on the single-set reads only. A page of sets would

        mean one catalog round-trip per rule per set, and the collection view has

        no use for connector logos - the set''s own name is what a picker shows.'
    ConnectorRule:
      oneOf:
      - properties:
          actionIds:
            items:
              type: string
            type:
            - array
            - 'null'
          connectionDefinitionId:
            $ref: '#/components/schemas/ConnectionDefinitionId'
          methods:
            items:
              $ref: '#/components/schemas/Method'
            type:
            - array
            - 'null'
          type:
            enum:
            - connectionDefinition
            type: string
        required:
        - connectionDefinitionId
        - type
        type: object
    PermissionSetBody:
      properties:
        connectorRules:
          description: 'The connectors this set grants. `null` (or omitted) creates the

            **allow-all** set, which grants every connector - the named,

            referenceable equivalent of authorizing with no set at all.'
          items:
            $ref: '#/components/schemas/ConnectorRule'
          type:
          - array
          - 'null'
        name:
          $ref: '#/components/schemas/NonEmptyString'
      required:
      - name
      type: object
    OAuthClientCreatedView:
      description: View that includes the plain client secret - only used on creation
      properties:
        accessTokenTtl:
          format: int32
          type:
          - integer
          - 'null'
        clientId:
          type: string
        clientSecret:
          type:
          - string
          - 'null'
        clientType:
          type: string
        consentSurface:
          $ref: '#/components/schemas/ConsentSurface'
        createdAt:
          format: date-time
          type: string
        description:
          type:
          - string
          - 'null'
        grantTypes:
          items:
            type: string
          type: array
        homepageUrl:
          type:
          - string
          - 'null'
        id:
          $ref: '#/components/schemas/OAuthClientId'
        isActive:
          type: boolean
        logoUrl:
          type:
          - string
          - 'null'
        name:
          type: string
        redirectUris:
          items:
            type: string
          type: array
      required:
      - id
      - clientId
      - name
      - redirectUris
      - clientType
      - grantTypes
      - isActive
      - consentSurface
      - createdAt
      type: object
    EnvelopeView:
      description: 'What a connector rule lets through, as every surface publishes it.


        **Absent means unrestricted, on the way out and on the way back in.** A

        submission that omits `methods` asks for *every* method, so a client offered

        a narrowed connector sends this envelope back verbatim or its submission is

        refused as widening - and "copy what is there, omit what is not" therefore

        produces a valid submission in every case. Published without it, a narrowed

        offer was impossible to accept at all.


        One type rather than one per surface: the held rule and the ask it is

        bounded by are the same envelope answering the same round-trip contract, and

        two definitions of it would eventually disagree.'
      properties:
        allowedActions:
          description: 'Resolved titles for the rule''s `action_ids`, present only when the rule

            narrows to a specific set (i.e. a custom rule). `None` means every

            action on the connector, which a customer-facing UI labels

            generically rather than listing.'
          items:
            $ref: '#/components/schemas/AllowedActionView'
          type:
          - array
          - 'null'
        methods:
          items:
            $ref: '#/components/schemas/Method'
          type:
          - array
          - 'null'
      type: object
    CreateParams:
      properties:
        accessTokenTtl:
          description: Access-token lifetime in seconds. One of the offered choices, or null for the platform default; any other value is refused.
          enum:
          - 604800
          - 2592000
          - 7776000
          - 31536000
          - null
          format: int32
          type:
          - integer
          - 'null'
        clientType:
          type: string
        consentSurface:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ConsentSurface'
            description: 'Where this client''s users grant consent. Omit for `hosted`, the page

              core renders itself.'
        description:
          type:
          - string
          - 'null'
        homepageUrl:
          type:
          - string
          - 'null'
        logoUrl:
          type:
          - string
          - 'null'
        name:
          $ref: '#/components/schemas/NonEmptyString'
        redirectUris:
          items:
            type: string
          type: array
      required:
      - name
      - clientType
      - redirectUris
      type: object
    AllowedActionView:
      properties:
        id:
          description: 'The action''s **`system_id`**, not its row id.


            This is the identifier a rule''s `actionIds` carries and the one both

            the permission-set editor and the consent submission are validated

            against, so it is the only id a client can send back. Publishing the

            row id instead round-trips into an action that resolves to a different

            connector, which consent now refuses as foreign.'
          type: string
        title:
          type: string
      required:
      - id
      - title
      type: object
    ConnectionDefinitionId:
      description: Prefixed ID with 'conn_def' prefix (e.g., 'conn_def_1C'), also accepts raw integer
      type: string
    Method:
      enum:
      - OPTIONS
      - GET
      - POST
      - PUT
      - DELETE
      - HEAD
      - TRACE
      - CONNECT
      - PATCH
      type: string
    Paginated_ClientUserView:
      properties:
        page:
          format: int64
          minimum: 0
          type: integer
        pages:
          format: int64
          minimum: 0
          type: integer
        rows:
          items:
            description: 'One user''s standing with an OAuth client, as its developer sees them.


              Carries `reach` in the same consent vocabulary as

              [`crate::domain::oauth_authorization::OAuthAuthorizationView`], so the two

              sides of the ledger report a grant identically.'
            properties:
              createdAt:
                format: date-time
                type: string
              email:
                type: string
              expiresAt:
                description: 'When the user''s current access token for this client expires. `None`

                  while they hold a live grant but no live token - the window between

                  re-consent and the client redeeming the new code.'
                format: date-time
                type:
                - string
                - 'null'
              lastUsedAt:
                format: date-time
                type:
                - string
                - 'null'
              name:
                type:
                - string
                - 'null'
              reach:
                description: 'What a grant reaches, generic over how each entry is rendered - the one

                  trichotomy two surfaces share: a dashboard reads it as counts

                  ([`GrantedReachView`]), a reconnect card as pre-selectable rules

                  ([`PriorGrantView`]). `KnowledgeOnly`/`Full` are identical on the wire for

                  both; only the `Connectors` element type differs.


                  A bare generic derives a single schema named `ReachView`, so both

                  instantiations would collide on that one OpenAPI component and one endpoint

                  would advertise the other''s connector shape. Every schema site that carries

                  one of these therefore inlines it (`#[schema(inline)]` / `inline(...)`), so

                  no shared `ReachView` component exists to collide.'
                oneOf:
                - description: 'Docs and search only: no connection access of any kind.'
                  properties:
                    type:
                      enum:
                      - knowledgeOnly
                      type: string
                  required:
                  - type
                  type: object
                - description: 'Every connection in the consented scope. No connector list because the

                    grant names none - it follows the account.'
                  properties:
                    type:
                      enum:
                      - full
                      type: string
                  required:
                  - type
                  type: object
                - description: 'Only what the grant names, each entry rendered as `C`. **The granularity

                    is the instantiation''s**: a reach report carries one entry per

                    connector, a prior grant one per granted *connection*, so two entries

                    there can share a connector.'
                  properties:
                    connectors:
                      items:
                        $ref: '#/components/schemas/GrantedConnectorView'
                      type: array
                    type:
                      enum:
                      - connectors
                      type: string
                  required:
                  - connectors
                  - type
                  type: object
              scopes:
                items:
                  type: string
                type: array
              tokenCount:
                minimum: 0
                type: integer
              userId:
                format: uuid
                type: string
              username:
                type: string
            required:
            - userId
            - email
            - username
            - scopes
            - reach
            - createdAt
            - tokenCount
            type: object
          type: array
        total:
          format: int64
          minimum: 0
          type: integer
      required:
      - rows
      - total
      - pages
      - page
      type: object
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://api.withone.ai/oauth/authorize
          scopes:
            org:ai_skills:read: Read organization AI skills
            org:ai_skills:write: Create, update, and delete organization AI skills
            org:authkit:read: Read organization AuthKit resources
            org:authkit:write: Create, update, and delete organization AuthKit resources
            org:connections:read: Read organization connections
            org:connections:write: Create, update, and delete organization connections
            org:projects:read: Read organization projects
            org:projects:write: Create, update, and delete organization projects
            org:secrets:read: Read organization secrets
            org:secrets:write: Create, update, and delete organization secrets
            org:workflows:executions:read: Read organization workflow executions
            org:workflows:executions:write: Create, update, and delete organization workflow executions
            org:workflows:read: Read organization workflows
            org:workflows:write: Create, update, and delete organization workflows
            project:ai_skills:read: Read project AI skills
            project:ai_skills:write: Create, update, and delete project AI skills
            project:authkit:read: Read project AuthKit resources
            project:authkit:write: Create, update, and delete project AuthKit resources
            project:connections:read: Read project connections
            project:connections:write: Create, update, and delete project connections
            project:secrets:read: Read project secrets
            project:secrets:write: Create, update, and delete project secrets
            project:workflows:executions:read: Read project workflow executions
            project:workflows:executions:write: Create, update, and delete project workflow executions
            project:workflows:read: Read project workflows
            project:workflows:write: Create, update, and delete project workflows
            user:ai_skills:read: Read your personal AI skills
            user:ai_skills:write: Create, update, and delete your personal AI skills
            user:authkit:read: Read your personal AuthKit resources
            user:authkit:write: Create, update, and delete your personal AuthKit resources
            user:connections:read: Read your personal connections
            user:connections:write: Create, update, and delete your personal connections
            user:secrets:read: Read your personal secrets
            user:secrets:write: Create, update, and delete your personal secrets
            user:workflows:executions:read: Read your personal workflow executions
            user:workflows:executions:write: Create, update, and delete your personal workflow executions
            user:workflows:read: Read your personal workflows
            user:workflows:write: Create, update, and delete your personal workflows
          tokenUrl: https://api.withone.ai/oauth/token
      type: oauth2
    Session:
      in: cookie
      name: withone
      type: apiKey
    X-One-Connection-Key:
      in: header
      name: X-One-Connection-Key
      type: apiKey
    X-One-Secret:
      in: header
      name: X-One-Secret
      type: apiKey
    X-Pica-Connection-Key:
      in: header
      name: X-One-Connection-Key
      type: apiKey
    X-Pica-Secret:
      in: header
      name: X-One-Secret
      type: apiKey