Skip to main content

Access Control API

See Entity Access Control for what an Access Control object is and which kinds of entities support attaching one. This page covers creating and managing Access Control objects themselves through the Management API.

Creating an Access Control object​

curl -X POST "https://{your-id-server}/api/rest/v1/accesscontrol" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Support team custom fields",
    "description": "Read/write access for the support team, read-only for everyone else in the group",
    "userIdRead": [],
    "userIdWrite": [],
    "groupIdRead": ["{everyoneGroupId}"],
    "groupIdWrite": ["{supportTeamGroupId}"],
    "apiClientIdRead": [],
    "apiClientIdWrite": []
  }'

Requires the ACCESS_CONTROL_CREATE permission. userIdRead/userIdWrite, groupIdRead/groupIdWrite, and apiClientIdRead/apiClientIdWrite each list the Users, Groups, or Management API Clients that should have read-only, or read and write, access — write access implies read access, so a subject only needs to be listed once. The response includes the new object's id, which is what you'll attach to an entity in the next step.

Reading, updating, and deleting an Access Control object​

curl "https://{your-id-server}/api/rest/v1/accesscontrol/{accessControlId}" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

Requires ACCESS_CONTROL_VIEW to read, ACCESS_CONTROL_MODIFY to PUT an update, and ACCESS_CONTROL_REMOVE to DELETE. Updating replaces the whole object, the same way as most other Management API resources.

Attaching it to an entity​

An Access Control object only has an effect once something references its id. For example, a Custom Field definition's accessControls field is an array of Access Control object IDs controlling who can read or write custom field values matching that definition:

curl -X PUT "https://{your-id-server}/api/rest/v1/customfield/{customFieldModelId}" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "supportTicketId",
    "accessControls": ["{accessControlId}"]
  }'

Updating replaces the whole Custom Field definition, so read the current one first and modify it, rather than sending only the fields you're changing.

The field on the referencing entity varies — see Entity Access Control for the current list of entities that support it, or search your instance's /apidoc for accessControlIds or accessControls.

Last updated on