openapi: 3.1.0
info:
  title: Accounting subpackage_applicationCredentials API
  version: 1.0.0
servers:
- url: https://api.merge.dev/api
- url: https://api-eu.merge.dev/api
- url: https://api-ap.merge.dev/api
tags:
- name: subpackage_applicationCredentials
paths:
  /api/v1/application-credentials/:
    get:
      operationId: list
      summary: List application credentials
      description: Lists OAuth application credentials for the organization.
      tags:
      - subpackage_applicationCredentials
      parameters:
      - name: external_id
        in: query
        description: Filter by external_id
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        schema:
          type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: slug
        in: query
        description: Filter by connector slug
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedApplicationCredentialPublicResponseList'
    post:
      operationId: create
      summary: Create application credential
      description: Creates an OAuth application credential for a connector. The `external_id` field is optional — omit it unless you need multiple OAuth apps for the same connector (e.g. one per customer tenant).
      tags:
      - subpackage_applicationCredentials
      parameters:
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCredentialPublicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationCredentialPublicCreate'
  /api/v1/application-credentials/{id}/:
    get:
      operationId: retrieve
      summary: Get application credential
      description: Retrieves an OAuth application credential by ID.
      tags:
      - subpackage_applicationCredentials
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCredentialPublicResponse'
    delete:
      operationId: destroy
      summary: Delete application credential
      description: Deletes an OAuth application credential. This also deletes all associated user credentials.
      tags:
      - subpackage_applicationCredentials
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
    patch:
      operationId: partial-update
      summary: Update application credential
      description: Partially updates an OAuth application credential. Only fields included in the request body are updated; omitted fields are left unchanged. Pass null to explicitly clear a field (e.g. client_secret or external_id).
      tags:
      - subpackage_applicationCredentials
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Token-based authentication with required prefix "Bearer"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCredentialPublicResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedApplicationCredentialUpdate'
components:
  schemas:
    ApplicationCredentialPublicCreate:
      type: object
      properties:
        connector_slug:
          type: string
          description: Slug of the connector to create an OAuth app for.
        client_id:
          type: string
        client_secret:
          type:
          - string
          - 'null'
        external_id:
          type:
          - string
          - 'null'
      required:
      - connector_slug
      - client_id
      description: Public API request body for creating an application credential.
      title: ApplicationCredentialPublicCreate
    PatchedApplicationCredentialUpdate:
      type: object
      properties:
        client_id:
          type: string
        client_secret:
          type:
          - string
          - 'null'
        external_id:
          type:
          - string
          - 'null'
      title: PatchedApplicationCredentialUpdate
    PaginatedApplicationCredentialPublicResponseList:
      type: object
      properties:
        count:
          type: integer
        next:
          type:
          - string
          - 'null'
        previous:
          type:
          - string
          - 'null'
        results:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationCredentialPublicResponse'
      required:
      - count
      - next
      - previous
      - results
      title: PaginatedApplicationCredentialPublicResponseList
    ApplicationCredentialPublicResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        connector_slug:
          type: string
        client_id:
          type: string
        external_id:
          type:
          - string
          - 'null'
        is_global_default:
          type: boolean
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
      required:
      - id
      - connector_slug
      - client_id
      - external_id
      - is_global_default
      - created_at
      - modified_at
      description: Public API response — excludes scope override fields.
      title: ApplicationCredentialPublicResponse
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
      description: Token-based authentication with required prefix "Bearer"