Sharing API

DoiT Cloud Analytics resources are content objects such as Alerts, Budgets, Allocations, and Reports that help you build FinOps capabilities. Sharing these resources with co-workers and stakeholders is essential for fostering financial accountability and driving informed decision-making in an organization.

The Sharing API provides a unified approach to managing content permissions.

Required permissions

To use the Sharing API, you need the following permissions:

Cloud Analytics User.
Depending on the resource you want to share, you may need extra permissions, for example, Allocations Admin. See Roles and permissions.

You must also meet one of the following criteria:

You are the Owner or the Editor of the resource.
You have the Editor permission on the resource.
You have the Cloud Analytics Admin permission.

Operations

GET /sharing/v1/{resourceType}/{resourceId}: Retrieves the permissions of the specified Cloud Analytics resource.
PUT /sharing/v1/{resourceType}/{resourceId}: Updates the permissions of the specified Cloud Analytics resource.

Schema

Below is the schema of the request body object of PUT /sharing/v1/{resourceType}/{resourceId}:

Property	Type	Description
permissions	array of objects	Attributes: `user`: string. Email address of the target user. For alerts, budgets, and reports, this field also supports the Microsoft Teams subdomain (`teams.ms`) or Slack subdomain (`slack.com`). `role`: Possible values: `owner`, `editor`, `viewer`
public	string enum	Specifies the permission granted to the whole organization. Possible values: `editor`, `viewer` If this field is left null or empty, the related resource is not visible at the organization level.

Example

📘
YOUR_API_KEY
Replace "YOUR_API_KEY" with your actual API key as explained at Get Started

Update resource permission

Below is an example request to update the permissions of a report specified by the resource ID. Note that you must provide the full permission list in the request body when updating permissions.

curl --request PUT \
     --url https://api.doit.com/sharing/v1/reports/{REPORT_ID} \
     --header 'Authorization: Bearer {YOUR_API_KEY}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "permissions": [
    {
      "user": "[email protected]",
      "role": "editor"
    },
    {
      "user": "[email protected]",
      "role": "owner"
    },
    {
      "user": "[email protected]",
      "role": "viewer"
    },
    {
      "user": "[email protected]",
      "role": "viewer"
    },
  ],
  "public": "viewer"
}
'