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:

Every principal the report is shared with, each with its user/team identity and access level resolved.

List report sharesGET /api/reports/admin:sales-overview/shares

Every principal the report is shared with, with the user/team identity and access level resolved.

Response · 200

[
  {
    "reportId": "00000000-0000-4000-8000-000000000001",
    "principalId": "annie.larson",
    "accessLevel": 1,
    "id": "annie.larson",
    "teamId": null,
    "name": "Annie Larson",
    "materialIcon": null,
    "icon": null,
    "color": null,
    "username": "annie.larson",
    "displayName": "Annie Larson",
    "email": "annie.larson@example.com",
    "avatarUpdatedAt": null,
    "type": "User",
    "avatarColor": {
      "background": "#81C784",
      "text": "#1B5E20"
    },
    "colorIndex": 4,
    "initials": "AL"
  }
]

Captured from the API examples test suite; ids and timestamps are normalized.

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:

Get a single shareGET /api/reports/admin:sales-overview/shares/annie.larson

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/reports/admin%3Asales-overview/shares/annie.larson"
    }
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "tenant": "acme",
  "reportId": "00000000-0000-4000-8000-000000000002",
  "principalId": "annie.larson",
  "accessLevel": 1,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z"
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

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:

Responds 200. accessLevel must be an integer > 0; to revoke, use DELETE rather than accessLevel: 0.

Share a report with a principalPUT /api/reports/admin:sales-overview/shares/annie.larson

principalId is a username (user) or team id. accessLevel is an integer > 0 (1 Member … 6 Admin). To revoke, use DELETE rather than accessLevel 0.

Request body

{
  "accessLevel": 1
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/reports/admin%3Asales-overview/shares/annie.larson"
    }
  },
  "tenant": "acme",
  "id": "00000000-0000-4000-8000-000000000001",
  "reportId": "00000000-0000-4000-8000-000000000002",
  "principalId": "annie.larson",
  "accessLevel": 1,
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z",
  "_altid": null
}

Captured from the API examples test suite; ids and timestamps are normalized.

Behavior:

• Creates a new share if one doesn't exist
• Updates access level if share already exists

---

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:

Responds 200 on success.

Remove a shareDELETE /api/reports/admin:sales-overview/shares/annie.larson

Revokes the principal’s access to the report.

Response · 200 · no body

Captured from the API examples test suite; ids and timestamps are normalized.

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