Sharing

Endpoints for managing template sharing and access control.

Sharing Overview

Templates can be shared with users or teams at different access levels:

• Read - View template and render
• Write - Modify template files, processors, inputs
• Share - Manage who has access

Templates can also be marked as shared: true to make them globally accessible within the tenant.

GET /api/templates/{id}/shares

Get all shares for a template.

Authentication: Required (session)

Pre-blocks: template.lookup(params.id)

Response:

{
  "_links": {
    "self": { "href": "/api/templates/{id}/shares" }
  },
  "_embedded": {
    "inf:share": [
      {
        "templateId": "abc123",
        "principalId": "engineering-team",
        "accessLevel": 2,
        "type": "Team",
        "name": "Engineering Team",
        "materialIcon": "engineering",
        "color": "#4CAF50",
        "_links": {
          "self": { "href": "/api/templates/abc123/shares/engineering-team" }
        }
      },
      {
        "templateId": "abc123",
        "principalId": "jane",
        "accessLevel": 1,
        "type": "User",
        "name": "Jane Smith",
        "username": "jane",
        "email": "jane@example.com",
        "avatarUrl": "/api/users/jane/avatar?t=1705327800000",
        "_links": {
          "self": { "href": "/api/templates/abc123/shares/jane" }
        }
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

Access Levels:

• 0 - No access (removes share)
• 1 - Read access
• 2 - Write access
• 3 - Share access (includes write)

---

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

Get a specific share for a user or team.

Authentication: Required (session)

Pre-blocks: template.lookup(params.id)

Response:

{
  "templateId": "abc123",
  "principalId": "engineering-team",
  "accessLevel": 2,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Error Response:

Returns 404 Not Found if share does not exist.

---

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

Create or update a share for a user or team.

Authentication: Required (session)

Pre-blocks: template.lookup(params.id), permission.template.share(pre.template)

Request Body:

Field	Type	Required	Description
accessLevel	integer	Yes	Access level: 0 (none), 1 (read), 2 (write), 3 (share)

Example Request:

{
  "accessLevel": 2
}

Response:

Returns the created or updated share object.

Side Effects:

• Creates activity log entry for new shares
• Updates activity log entry for modified shares
• Grants template access to specified user or team

---

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

Remove a share, revoking access for a user or team.

Authentication: Required (session)

Pre-blocks: template.lookup(params.id), permission.template.share(pre.template)

Response:

Returns 204 No Content on successful deletion.

Side Effects:

• Revokes template access for specified user or team
• Does not affect template owner access

---

Permission Mapping

Share access levels map to permissions:

Access Level	Read	Write	Share
0 - None	✗	✗	✗
1 - Read	✓	✗	✗
2 - Write	✓	✓	✗
3 - Share	✓	✓	✓

Template Ownership:

• Template owner always has full access (share level)
• Owners can change via PUT /api/templates/{id}/owner
• Sharing requires permission.template.share

Global Sharing:

• Set shared: true via PUT /api/templates/{id} to make template accessible to all users in tenant
• Global sharing requires permission.template.write