The Access Search Service, or commonly, ’the Search API’ is divided into two parts.
Most commonly, when referring to the Search API, one is discussing the Asset Search Service. This API answers the question:
What Assets can this Principal perform this Action on?
The other half of the Access Search Service is the Principal Search Service, capable of answering the flip-side of the above, namely:
Which Principals can perform this Action on this Asset?
See below for more detail related to these APIs, their use-cases, and some samples for how to use them yourself.
The Asset Search API shifts the focus to the “what” instead of the “who”. It allows organizations to answer the following question:
What Assets can this Principal perform this Action on?
The Asset Search API is crafted for this purpose. It returns the set of organizational assets a principal (user, service, robot or system) can access. The response also contains all attributes of the assets, allowing the caller to take further action on the response.
curl --location 'https://{yourClientName}.sgnlapis.cloud/access/v2/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Authentication Token for the Protected System>' \
--data-raw '{
"principal": {
"id": "john.doe@acme.com"
},
"queries": [
{
"action": "read"
}
]
}'
{
"decisions": [
{
"action": "read",
"assetAttributes": {
"fields__assignee__displayName": "John Doe",
"fields__assignee__email": "john.doe@acme.com",
"fields__assignee__timeZone": "America/Los_Angeles",
"fields__priority__id": "3",
"fields__priority__name": "Medium",
"fields__status__name": "Approved Active",
"fields__status__statusCategory__name": "In Progress",
"fields__summary": "Issue Summary goes here",
"id": "10075",
"key": "Issue-314",
"self": "https://sgnl01.atlassian.net/rest/api/3/issue/10075"
},
"assetId": "Issue-314",
"decision": "Allow"
}
],
"evaluationDuration": 61,
"issuedAt": "2023-11-08T03:22:38.002077146Z",
"principalId": "john.doe@acme.com"
}
You can also customize the format of the inbound request and response, depending on the system that is calling SGNL. Out of the box, SGNL provides support for Okta and Entra ID formats, without any additional configuration. We also enable the request and response to be totally customized with Custom Transforms.
The SGNL Asset Search API documentation can be found on our API Documentation Page.
Sometimes, organizations need to flip the perspective and ask the question:
Which Principals can perform this Action on this Asset?
The Principal Search API is crafted for this purpose. It returns the set of principals (user, service, robot or system) that are permitted by policy to perform the specified actions on the asset. The response also contains all attributes of the principal, allowing the caller to take further action on the response.
curl --location 'https://{yourClientName}.sgnlapis.cloud/access/v2/search/principals' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Authentication Token for the Protected System>' \
--data '{
"queries": [{
"action": "read",
"assetId": "Issue-314"
}]
}'
We see that two decisions have been returned by the Principal Search API. One for John Doe because there is a policy to allow users in the Engineering department read access to the Jira issue assigned to them. The second user allowed read access belongs to the Customer Support department.
{
"decisions": [
{
"action": "read",
"assetId": "Issue-314",
"decision": "Allow",
"principalAttributes": {
"id": "00u3lfyyhvzycNQ7s1d7",
"profile__department": "Engineering",
"profile__email": "john.doe@acme.com",
"profile__firstName": "John",
"profile__lastName": "Doe",
"profile__login": "john.doe@acme.com",
"profile__managerId": "00u3l9uuweKaafPXr1d7",
"status": "ACTIVE"
},
"principalId": "john.doe@acme.com"
},
{
"action": "read",
"assetId": "10075",
"decision": "Allow",
"principalAttributes": {
"id": "00u4uuhxg6zEaMabV1d7",
"profile__department": "Customer Support",
"profile__email": "alejandro.bacong@acme.com",
"profile__firstName": "Alejandro",
"profile__lastName": "Bacong",
"profile__login": "alejandro.bacong@acme.com",
"status": "ACTIVE"
},
"principalId": "alejandro.bacong@acme.com"
}
],
"evaluationDuration": 72,
"issuedAt": "2023-11-08T04:47:13.441399713Z"
}
The SGNL Principal Search API documentation can be found on our API Documentation Page