DoiT Sharing API

openapi: 3.2.0
info:
  title: DoiT Sharing API
  description: Programmatic access to DoiT Platform
  version: v1
servers:
- url: https://api.doit.com
security:
- api_key: []
- tenantId: []
  api_key: []
tags:
- name: Sharing
  description: Manage permissions associated with specified Cloud Analytics resources.
paths:
  /sharing/v1/{resourceType}/{resourceId}:
    get:
      tags:
      - Sharing
      summary: Get resource permissions
      description: 'Returns the permissions associated with the specified Cloud Analytics resource.

        Supports Allocations, Alerts, Budgets, and Reports.'
      operationId: getResourcePermission
      parameters:
      - $ref: '#/components/parameters/resourceType'
      - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: OK - Resource permissions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourcePermissionsResponse'
        '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'
    put:
      tags:
      - Sharing
      summary: Update resource permissions
      description: 'Updates the permissions associated with the specified Cloud Analytics resource.

        Supports Allocations, Alerts, Budgets, and Reports.'
      operationId: updateResourcePermission
      parameters:
      - $ref: '#/components/parameters/resourceType'
      - $ref: '#/components/parameters/resourceId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                permissions:
                  type: array
                  items:
                    $ref: '#/components/schemas/ResourcePermission'
                public:
                  type:
                  - string
                  - 'null'
                  description: 'The type of permissions granted to all users in the organization for this resource.


                    Allocations (single and group) always have at least `viewer` public access, so it cannot be cleared:

                    - If `public` is omitted, the stored value is kept.

                    - An empty string (`""`) is accepted for backward compatibility and is treated as `viewer`.

                    - An explicit `null` is rejected with `400 Bad Request`.


                    For Reports, Budgets, and Alerts, an omitted or `null` value sets `public` to `null` (no public access).'
                  enum:
                  - editor
                  - viewer
      responses:
        '200':
          description: OK - Resource permissions configuration updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourcePermissionsResponse'
        '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.
    ResourcePermissionsResponse:
      type: object
      description: Permissions and metadata for a resource returned by the sharing API.
      properties:
        id:
          type: string
          description: Resource ID.
        name:
          type: string
          description: Resource name.
        description:
          type: string
          description: Resource description.
        createTime:
          type: integer
          description: The time when this resource was created, in milliseconds since the epoch.
          format: int64
        updateTime:
          type: integer
          description: The time when this resource was last updated, in milliseconds since the epoch.
          format: int64
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/ResourcePermission'
        public:
          type:
          - string
          - 'null'
          description: Type of permissions users in the entire organization have for this resource
          enum:
          - editor
          - viewer
    ResourcePermission:
      type: object
      description: A single user's permission entry for a resource.
      properties:
        user:
          type: string
          description: The email address of the user to whom the role is assigned.
        role:
          type: string
          description: The role assigned to the user, defining their level of access to the resource.
          enum:
          - owner
          - editor
          - viewer
  parameters:
    resourceType:
      name: resourceType
      in: path
      description: Resource type.
      required: true
      schema:
        type: string
        enum:
        - alerts
        - budgets
        - reports
        - allocations
    resourceId:
      name: resourceId
      in: path
      description: Resource ID. See [Resource IDs](https://developer.doit.com/docs/resource-ids).
      required: true
      schema:
        type: string
  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'
  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)