Sharing

Share a datasource with other principals (users or teams), optionally limiting access to specific mapping sets and hiding specific fields. Shares are keyed by principalId — a username or a team id — exactly like dataset shares.

All write routes require the datasource:share permission.

Access levels:

accessLevel	Meaning
0	No access
1	Mapping-set restricted — combine with mappingSetAccess (per-set levels) and noAssignedSetsAccessLevel
2	Full access

GET /api/datasources/{id}/shares

List every share on the datasource. A HAL collection (rel inf:datasource-all-shares); each entry resolves the principal and summarizes its mapping-set access counts and restricted fields.

List datasource sharesGET /api/datasources/admin:northwind/shares

GET /api/datasources/{id}/shares returns every share (rel inf:datasource-all-shares), each with the principal resolved and the share’s mapping-set access counts and restricted fields summarized.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasources/admin%3Anorthwind/shares"
    }
  },
  "start": 0,
  "count": 1,
  "total": 1,
  "_embedded": {
    "inf:datasource-share": [
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000001/shares/marketing"
          },
          "inf:datasource-share-fields": {
            "href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000001/shares/marketing/fields"
          }
        },
        "id": "marketing",
        "datasourceId": "00000000-0000-4000-8000-000000000001",
        "principalId": "marketing",
        "accessLevel": 2,
        "noAssignedSetsAccessLevel": 0,
        "teamId": "marketing",
        "name": "Marketing",
        "materialIcon": null,
        "icon": "fa-bullhorn",
        "color": "red",
        "username": null,
        "displayName": null,
        "email": null,
        "avatarUpdatedAt": null,
        "type": "Team",
        "mappingSetAccess": {},
        "fullMappingSetCount": 0,
        "restrictedMappingSetCount": 0,
        "restrictedFields": [],
        "restrictedFieldNames": []
      }
    ]
  }
}

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

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

Create or update a share (upsert — repeat to change the grant).

Field	Type	Required	Description
accessLevel	integer	Yes	0, 1, or 2 (see above).
mappingSetAccess	object	No	Per-mapping-set access levels, used when accessLevel is 1.
noAssignedSetsAccessLevel	integer	No	Access level for mappings in no assigned set.
restrictedFields	array	No	Field ids to hide from this principal.

Returns 200 with the share. Newly granting access (from none) notifies the principal.

Share a datasourcePUT /api/datasources/admin:northwind/shares/marketing

PUT /api/datasources/{id}/shares/{principalId} grants a principal (username or team id) access. accessLevel 2 = full; 1 = mapping-set-restricted (pair with mappingSetAccess and noAssignedSetsAccessLevel); 0 = no access. restrictedFields hides specific fields. Requires datasource:share. Upserts: repeat to change the grant. Returns the share.

Request body

{
  "accessLevel": 2,
  "restrictedFields": []
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasources/admin%3Anorthwind/shares/marketing"
    }
  },
  "tenant": "acme",
  "id": "00000000-0000-4000-8000-000000000001",
  "datasourceId": "00000000-0000-4000-8000-000000000002",
  "principalId": "marketing",
  "accessLevel": 2,
  "noAssignedSetsAccessLevel": 0,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "_altid": null
}

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

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

Get one share, including its mappingSetAccess map and sharedFields.

Get one datasource shareGET /api/datasources/admin:northwind/shares/marketing

GET /api/datasources/{id}/shares/{principalId} returns the share with its mappingSetAccess map and sharedFields.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasources/admin%3Anorthwind/shares/marketing"
    },
    "inf:datasource-share-fields": {
      "href": "https://informer.example.com/api/datasources/admin%3Anorthwind/shares/marketing/fields"
    }
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "tenant": "acme",
  "datasourceId": "00000000-0000-4000-8000-000000000002",
  "principalId": "marketing",
  "accessLevel": 2,
  "noAssignedSetsAccessLevel": 0,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "shareSets": [],
  "shareFields": [],
  "mappingSetAccess": {},
  "sharedFields": []
}

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

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

Revoke a principal's access. Returns 200 with an empty body.

Revoke a datasource shareDELETE /api/datasources/admin:northwind/shares/everett

DELETE /api/datasources/{id}/shares/{principalId} revokes the principal’s access and returns 200 with an empty body. Requires datasource:share.

Response · 200 · no body

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

Field-level restrictions

Beyond restrictedFields on the share itself, a share's hidden fields can be managed individually.

GET /api/datasources/{id}/shares/{principalId}/fields

List the share's restricted-field entries.

List a share’s restricted fieldsGET /api/datasources/admin:northwind/shares/marketing/fields

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasources/admin%3Anorthwind/shares/marketing/fields"
    }
  },
  "start": 0,
  "count": 1,
  "total": 1,
  "_embedded": {
    "inf:datasource-share-field": [
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/datasources/admin%3Anorthwind/shares/marketing/fields/00000000-0000-4000-8000-000000000001%3Apublic%2Bemployees%3ABirthDate"
          }
        },
        "id": "00000000-0000-4000-8000-000000000002",
        "tenant": "acme",
        "datasourceShareId": "00000000-0000-4000-8000-000000000003",
        "fieldId": "00000000-0000-4000-8000-000000000001:public+employees:BirthDate",
        "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/datasources/{id}/shares/{principalId}/fields/{fieldId}

Add (upsert) a field restriction to the share. Returns 200.

Restrict a field for a sharePUT /api/datasources/admin:northwind/shares/marketing/fields/00000000-0000-4000-8000-000000000001:public+employees:BirthDate

PUT /api/datasources/{id}/shares/{principalId}/fields/{fieldId} adds a field-level restriction to the share (upsert). Requires datasource:share. Returns 200.

Request body

{}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasources/admin%3Anorthwind/shares/marketing/fields/00000000-0000-4000-8000-000000000001%3Apublic%2Bemployees%3ABirthDate"
    }
  },
  "id": "00000000-0000-4000-8000-000000000002",
  "tenant": "acme",
  "datasourceShareId": "00000000-0000-4000-8000-000000000003",
  "fieldId": "00000000-0000-4000-8000-000000000001:public+employees:BirthDate",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z"
}

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

GET /api/datasources/{id}/shares/{principalId}/fields/{fieldId}

Get a single restricted-field entry.

Get one restricted-field entryGET /api/datasources/admin:northwind/shares/marketing/fields/00000000-0000-4000-8000-000000000001:public+employees:BirthDate

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasources/admin%3Anorthwind/shares/marketing/fields/00000000-0000-4000-8000-000000000001%3Apublic%2Bemployees%3ABirthDate"
    }
  },
  "id": "00000000-0000-4000-8000-000000000002",
  "tenant": "acme",
  "datasourceShareId": "00000000-0000-4000-8000-000000000003",
  "fieldId": "00000000-0000-4000-8000-000000000001:public+employees:BirthDate",
  "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.

DELETE /api/datasources/{id}/shares/{principalId}/fields/{fieldId}

Remove a field restriction. Returns 200 with an empty body.

Remove a field restrictionDELETE /api/datasources/admin:northwind/shares/marketing/fields/00000000-0000-4000-8000-000000000001:public+employees:BirthDate

DELETE /api/datasources/{id}/shares/{principalId}/fields/{fieldId} removes the restriction and returns 200 with an empty body.

Response · 200 · no body

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