Sharing

Manage report access and sharing with users and teams.

Overview

Reports can be shared with individual users or entire teams with different access levels. Sharing controls who can view, edit, or manage a report.

GET /api/reports/{id}/shares

Get all shares for a report.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Response:

{
  "_links": {
    "self": { "href": "/api/reports/{id}/shares" }
  },
  "_embedded": {
    "inf:share": [
      {
        "reportId": "team:sales-dashboard",
        "principalId": "team:marketing",
        "accessLevel": 2,
        "id": "team:marketing",
        "teamId": "team:marketing",
        "name": "Marketing Team",
        "materialIcon": "group",
        "icon": null,
        "color": "#4CAF50",
        "type": "Team",
        "_links": {
          "self": { "href": "/api/reports/team:sales-dashboard/shares/team:marketing" }
        }
      },
      {
        "reportId": "team:sales-dashboard",
        "principalId": "user:jane.smith",
        "accessLevel": 1,
        "id": "user:jane.smith",
        "username": "jane.smith",
        "displayName": "Jane Smith",
        "email": "jane.smith@example.com",
        "avatarUrl": "/api/users/jane.smith/avatar?t=1707484800000",
        "type": "User",
        "_links": {
          "self": { "href": "/api/reports/team:sales-dashboard/shares/user:jane.smith" }
        }
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

Response Fields:

Field	Type	Description
principalId	string	User or team ID being granted access
accessLevel	integer	Access level (0=none, 1=view, 2=edit)
type	string	User or Team
name	string	Display name

User-specific fields:

• username, displayName, email, avatarUrl

Team-specific fields:

• teamId, materialIcon, icon, color

Use Case:

Display all users and teams with access to a report.

---

GET /api/reports/{id}/shares/{principalId}

Get a specific share by principal ID.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID
principalId	string	User or team ID (e.g., user:john.doe or team:analytics)

Response:

{
  "reportId": "team:sales-dashboard",
  "principalId": "user:jane.smith",
  "accessLevel": 2,
  "_links": {
    "self": { "href": "/api/reports/team:sales-dashboard/shares/user:jane.smith" }
  }
}

---

PUT /api/reports/{id}/shares/{principalId}

Grant or update access for a user or team.

Authentication: Required

Permissions: report:share

Path Parameters:

Parameter	Type	Description
id	string	Report ID
principalId	string	User or team ID

Request Body:

{
  "accessLevel": 2
}

Access Levels:

Level	Permission
0	No access
1	View only
2	Edit access

Response:

{
  "reportId": "team:sales-dashboard",
  "principalId": "user:jane.smith",
  "accessLevel": 2,
  "_links": {
    "self": { "href": "/api/reports/team:sales-dashboard/shares/user:jane.smith" }
  }
}

Status Code: 200 OK (update) or 201 Created (new share)

Behavior:

• Creates a new share if one doesn't exist
• Updates access level if share already exists
• Setting accessLevel: 0 effectively removes access

---

DELETE /api/reports/{id}/shares/{principalId}

Revoke access for a user or team.

Authentication: Required

Permissions: report:share

Path Parameters:

Parameter	Type	Description
id	string	Report ID
principalId	string	User or team ID

Response:

204 No Content on success.

Behavior:

• Removes the share entry
• User/team will no longer have explicit access
• May still have access via team membership or ownership

Use Case:

Revoke a previously granted share.

---

Access Control Model

Report access is determined by:

1. Ownership - Report owner has full access
2. Team Membership - Members of the owning team have access based on role
3. Explicit Shares - Individual shares grant specific access levels
4. Superuser - Superusers bypass all checks

Team Role Hierarchy

When a report is owned by a team:

Role	Implicit Access
Admin	Full control
Publisher	Edit and publish
Data Wizard	Edit
Designer	View/edit visuals
Member+	View with extended features
Member	View

Explicit shares can grant access beyond team membership.

---

Share Management Tips

Grant team-wide access:

PUT /api/reports/team:sales-dashboard/shares/team:marketing
{ "accessLevel": 1 }

Grant edit access to individual:

PUT /api/reports/team:sales-dashboard/shares/user:jane.smith
{ "accessLevel": 2 }

Revoke access:

DELETE /api/reports/team:sales-dashboard/shares/user:jane.smith

List all access:

GET /api/reports/team:sales-dashboard/shares