DoiT Shared Payers API

openapi: 3.2.0
info:
  title: DoiT Shared Payers API
  description: Programmatic access to DoiT Platform
  version: v1
servers:
- url: https://api.doit.com
security:
- api_key: []
- tenantId: []
  api_key: []
tags:
- name: Shared Payers
  description: Link and manage shared-payer account mappings for PartnerOps resellers (T2), reassigning AWS accounts under a shared payer to T3 end customers.
paths:
  /customers/v1/customers/{customerId}/shared-payer-accounts:
    get:
      tags:
      - Shared Payers
      summary: List shared-payer account mappings
      description: Lists the AWS accounts under the reseller's linked shared payers, together with the end customer each is currently mapped to. `{customerId}` (the reseller itself) means the account has not yet been reassigned to an end customer. Each payer's own management account is included alongside its member accounts. Requires the `SharedPayersAdmin` permission and DoiT API access (`platform:externalApi`). User API tokens must include the permission in their scope.
      operationId: listSharedPayerAccountMappings
      parameters:
      - $ref: '#/components/parameters/customerId'
      - name: managementAccount
        in: query
        description: Restricts the results to accounts under this AWS management (payer) account ID.
        schema:
          type: string
      responses:
        '200':
          description: OK - Shared-payer account mappings returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedPayerAccountMappingList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  /customers/v1/customers/{customerId}/shared-payer-accounts/management-accounts:
    get:
      tags:
      - Shared Payers
      summary: List shared-payer management accounts
      description: Lists the reseller's linked shared-payer management (payer) accounts that have completed onboarding, for use in an account picker. Requires the `SharedPayersAdmin` permission and DoiT API access (`platform:externalApi`). User API tokens must include the permission in their scope.
      operationId: listSharedPayerManagementAccounts
      parameters:
      - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: OK - Shared-payer management accounts returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedPayerManagementAccountList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  /customers/v1/customers/{customerId}/shared-payer-accounts/payers:
    get:
      tags:
      - Shared Payers
      summary: List shared payers with mapping progress
      description: Lists every shared payer linked to the reseller, including ones still mid-onboarding, with per-payer counts of linked and mapped accounts. Requires the `SharedPayersAdmin` permission and DoiT API access (`platform:externalApi`). User API tokens must include the permission in their scope.
      operationId: listSharedPayers
      parameters:
      - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: OK - Shared payers returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedPayerList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  /customers/v1/customers/{customerId}/shared-payer-accounts/{assetId}:
    patch:
      tags:
      - Shared Payers
      summary: Reassign a shared-payer account
      description: Reassigns one AWS account under a linked shared payer - a member account or the payer's own management account - to the reseller itself or to a T3 end customer within its hierarchy. Requires the `SharedPayersAdmin` permission and DoiT API access (`platform:externalApi`). User API tokens must include the permission in their scope.
      operationId: reassignSharedPayerAccount
      parameters:
      - $ref: '#/components/parameters/customerId'
      - name: assetId
        in: path
        required: true
        description: Asset ID of the AWS account to reassign, as returned by `listSharedPayerAccountMappings`.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SharedPayerAccountReassignRequest'
      responses:
        '200':
          description: OK - Account reassigned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedPayerAccountReassignResult'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    Error:
      type: object
      description: Standard error response structure.
      properties:
        error:
          type: string
          description: Detailed error message.
    SharedPayerAccountReassignRequest:
      type: object
      required:
      - customerId
      properties:
        customerId:
          type: string
          description: 'Customer to reassign the account to: `{customerId}` (the reseller itself) or a T3 end customer within its hierarchy.'
    SharedPayerAccountReassignResult:
      type: object
      properties:
        assetId:
          type: string
          description: Asset ID of the reassigned account.
        customerId:
          type: string
          description: Customer the account was reassigned to.
    SharedPayerAccountMapping:
      type: object
      description: One AWS account under a linked shared payer - a member account or the payer's own management account - and the customer it is currently mapped to.
      properties:
        assetId:
          type: string
          description: Asset ID of the AWS account.
        accountName:
          type: string
          description: Display name of the AWS account.
        accountId:
          type: string
          description: AWS account ID.
        payerId:
          type: string
          description: AWS account ID of the management (payer) account this account is under.
        payerName:
          type: string
          description: Display name of the management (payer) account.
        customerId:
          type: string
          description: Customer the account is currently mapped to. Equal to `{customerId}` (the reseller itself) when the account has not been reassigned to an end customer.
        customerName:
          type: string
          description: Display name of `customerId`.
    SharedPayer:
      type: object
      description: A shared payer linked to the reseller, with its account-mapping progress.
      properties:
        payerId:
          type: string
          description: AWS account ID of the management (payer) account.
        payerName:
          type: string
          description: Display name of the management (payer) account.
        linkedAccounts:
          type: integer
          description: Number of AWS accounts under this payer, including the payer's own management account.
        mappedAssets:
          type: integer
          description: Number of those accounts already reassigned to an end customer.
        totalAssets:
          type: integer
          description: Same as `linkedAccounts`.
        completed:
          type: boolean
          description: Whether the payer has finished onboarding. A payer still mid-onboarding has no accounts yet.
    SharedPayerManagementAccountList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SharedPayerManagementAccount'
    SharedPayerList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SharedPayer'
    SharedPayerAccountMappingList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SharedPayerAccountMapping'
    SharedPayerManagementAccount:
      type: object
      description: A linked shared-payer management (payer) account that has completed onboarding.
      properties:
        payerId:
          type: string
          description: AWS account ID of the management (payer) account.
        payerName:
          type: string
          description: Display name of the management (payer) account.
  responses:
    '404':
      description: Not Found - The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized - Invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Forbidden - The client is not authorized to perform the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error - Something went wrong with the DoiT API server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '400':
      description: Bad Request - The server cannot process the request, often due to a malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    customerId:
      name: customerId
      in: path
      required: true
      description: Customer ID. Must match the customer resolved from the bearer token - a token scoped to a different customer gets `403`.
      schema:
        type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      description: Use the "Bearer <API_KEY>" format or sign in for autofill
      in: header
    tenantId:
      type: apiKey
      name: X-Tenant-Id
      description: 'Customer (tenant) ID for the request. Separate from your API token: always authenticate with `Authorization: Bearer <token>` (personal or service account). See [Get Started](https://developer.doit.com/docs/start). Omit when your token is scoped to a single customer (resolved automatically). A service account can select an active direct or nested descendant of its home customer; the endpoint''s normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns `403 Forbidden`. Prefer this header over the legacy `customerContext` query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.'
      in: header
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://console.doit.com/sign-in/oauth
          tokenUrl: https://console.doit.com/api/auth/token
          scopes:
            dci: Access All Data
x-samples-languages:
- curl
- go
- node
- python
x-cli-config:
  security: oauth2
  params:
    client_id: cli
x-provenance:
  method: harvested
  publisher: DoiT
  source: https://api.doit.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)