Clerk Application Transfers API

openapi: 3.2.0
info:
  title: Clerk Platform Application Transfers API
  x-logo:
    url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
    altText: Clerk docs
    href: https://clerk.com/docs
  contact:
    email: support@clerk.com
    name: Clerk Platform Team
    url: https://clerk.com/support
  description: 'The Clerk REST Platform API, for programmatic management of resources of a workspace.


    > [!note]

    > This API is currently in private beta. If you''d like access for your workspace, please fill out and submit our [request form](https://clerkdev.notion.site/2df2b9ab44fe803f9031e9f3185c5e19).'
  version: BETA
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/openapi-specs/blob/main/LICENSE
servers:
- url: https://api.clerk.com/v1
security:
- platform_api_access_token: []
tags:
- name: Application Transfers
  description: 'An object representing a transfer request for an application between workspaces.


    The high-level flow for application transfer:


    1. The initial workspace can create an application transfer. A single-use `code` will be generated which may be distributed to any end-user of Clerk.

    2. The code must be claimed through the clerk dashboard: https://dashboard.clerk.com/apps/transfer?code=<...>


    Note that once a transfer is claimed, the original workspace will no longer have access to the application.'
paths:
  /platform/application_transfers:
    get:
      operationId: PlatformListApplicationTransfers
      x-speakeasy-group: platform
      x-speakeasy-name-override: listApplicationTransfers
      tags:
      - Application Transfers
      summary: List Application Transfers
      description: 'List all transfer requests created by the authenticated workspace. Returns

        transfers sorted by creation date in descending order (most recent first).


        Use the `status` parameter to filter by transfer status.

        '
      security:
      - platform_api_access_token: []
      parameters:
      - name: status
        in: query
        description: 'Filter by transfer status. Multiple values can be provided by repeating

          the parameter (e.g., `?status=pending&status=canceled`).

          '
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - pending
            - completed
            - canceled
            - expired
      - name: limit
        in: query
        description: Number of results to return per page (1-500, default 10).
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 10
      - name: starting_after
        in: query
        description: 'Cursor for pagination. Provide the ID of the last transfer from the

          previous page to get the next page of results.

          '
        required: false
        schema:
          type: string
      - name: ending_before
        in: query
        description: 'Cursor for pagination. Provide the ID of the first transfer from the

          previous page to get the previous page of results.

          '
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Application transfers retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformListApplicationTransfersResponse'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /platform/applications/{applicationID}/transfers:
    post:
      operationId: PlatformCreateApplicationTransfer
      x-speakeasy-group: platform
      x-speakeasy-name-override: createApplicationTransfer
      tags:
      - Application Transfers
      summary: Create an Application Transfer
      description: 'Create a new transfer request for an application. This initiates the process of

        transferring ownership of the application to another workspace.


        Only one pending transfer can exist for an application at a time. The transfer

        will expire after 24 hours if not completed.

        '
      security:
      - platform_api_access_token: []
      parameters:
      - name: applicationID
        in: path
        description: Application ID.
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Application transfer created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformApplicationTransferResponse'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '409':
          $ref: '#/components/responses/Conflict'
  /platform/applications/{applicationID}/transfers/{transferID}:
    get:
      operationId: PlatformGetApplicationTransfer
      x-speakeasy-group: platform
      x-speakeasy-name-override: getApplicationTransfer
      tags:
      - Application Transfers
      summary: Get an Application Transfer
      description: 'Retrieve details of an application transfer by its ID.

        '
      security:
      - platform_api_access_token: []
      parameters:
      - name: applicationID
        in: path
        description: Application ID.
        required: true
        schema:
          type: string
      - name: transferID
        in: path
        description: Application Transfer ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Application transfer retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformApplicationTransferResponse'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    delete:
      operationId: PlatformCancelApplicationTransfer
      x-speakeasy-group: platform
      x-speakeasy-name-override: cancelApplicationTransfer
      tags:
      - Application Transfers
      summary: Cancel an Application Transfer
      description: 'Cancel an existing application transfer. Only transfers in ''pending'' status can be canceled.

        '
      security:
      - platform_api_access_token: []
      parameters:
      - name: applicationID
        in: path
        description: Application ID.
        required: true
        schema:
          type: string
      - name: transferID
        in: path
        description: Application Transfer ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Application transfer canceled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformApplicationTransferResponse'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/Conflict'
components:
  responses:
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  schemas:
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    PlatformListApplicationTransfersResponse:
      title: List Application Transfers Response
      description: A paginated list of application transfers.
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          description: The list of application transfers.
          items:
            $ref: '#/components/schemas/PlatformApplicationTransferResponse'
        total_count:
          type: integer
          format: int64
          description: The total number of application transfers matching the query.
          example: 5
      required:
      - data
      - total_count
    PlatformApplicationTransferResponse:
      title: Application Transfer
      description: Represents an application transfer request. Application transfers allow transferring ownership of an application from one organization to another.
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - application_transfer
          description: The object type.
        id:
          type: string
          description: The unique identifier for the application transfer.
          example: appxfr_2abc123def456
        code:
          type: string
          description: 'A unique code for the transfer that can be shared with the recipient to claim the application through the clerk dashboard: https://dashboard.clerk.com/apps/transfer?code=<CODE>'
          example: 550e8400-e29b-41d4-a716-446655440000
        application_id:
          type: string
          description: The ID of the application being transferred.
          example: app_2abc123def456
        status:
          type: string
          description: The current status of the transfer.
          enum:
          - pending
          - completed
          - canceled
          - expired
          example: pending
        expires_at:
          type: string
          format: date-time
          description: The timestamp when the transfer expires if not completed.
          example: '2024-01-16T12:00:00Z'
        created_at:
          type: string
          format: date-time
          description: The timestamp when the transfer was created.
          example: '2024-01-15T12:00:00Z'
        canceled_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The timestamp when the transfer was canceled, or null if not canceled.
          example: null
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The timestamp when the transfer was completed, or null if not completed.
          example: null
      required:
      - object
      - id
      - code
      - application_id
      - status
      - expires_at
      - created_at
      - canceled_at
      - completed_at
  securitySchemes:
    platform_api_access_token:
      type: http
      scheme: bearer
      description: Platform API access token.
externalDocs:
  url: https://clerk.com/docs
x-tagGroups:
- name: Core Resources
  tags:
  - Applications
  - Domains
  - Application Transfers
  - Users
  - JWT Templates
  - Redirect URLs
  - Config