Skip to main content

API

Managing Policies

Policy controls how users or accounts can get access to a resource. Policy used by appeal to determine the approval flow, get creator's identity/profile, and decide whether it needs additional appeals. Policy is attached to a resource type in the provider config, thus a policy should be the first thing to setup before creating a provider and getting its resources.

Create Policy

Policies can be created by calling with a POST Method on {{HOST}}/api/v1beta1/policies

Parameters
NameLocated inDescriptionRequiredType
bodybodyContains a policy name, steps for approval flow, External identity manager(IAM)
details for authorization required for the accessing the resource
YesPolicy
X-Auth-EmailheaderContains the user/service account email used for authorizationYesstring
Responses
CodeDescriptionType
200A successful responsePolicy
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request POST '{{HOST}}/api/v1beta1/policies' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "my_policy",
"steps": [
{
"name": "manager_approval",
"description": "Manager approval for sensitive data",
"when": "$appeal.resource.details.is_sensitive == true",
"strategy": "manual",
"approvers": [
"$appeal.creator.manager_email"
]
},
{
"name": "resource_owner_approval",
"description": "Approval from resource admin/owner",
"strategy": "manual",
"approvers": [
"$appeal.resource.details.owner"
]
}
]
}'

Policy has version to ensure each appeal has a reference to an applied policy when it's created. A policy is created with an initial version equal to 1.

Check policy reference for more details on the policy configuration.

Updating Policy

Updating a policy actually means creating a new policy with the same id but the version gets incremented by 1. Both the new and previous policies still can be used by providers.

Policies can be updated by using the PUT Method on {{HOST}}/api/v1beta1/policies/:id

Parameters
NameLocated inDescriptionRequiredType
idpathUnique identifier for policy to be updatedYesString
bodybodyContains the fields reuired to be added/updated in the policyYesPolicy
Responses
CodeDescriptionType
200A successful response.Policy
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request PUT '{{HOST}}/api/v1beta1/policies/{{policy_id}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"steps": [
{
"name": "manager_approval",
"description": "Manager approval for sensitive data",
"when": "$appeal.resource.details.is_sensitive == true",
"strategy": "manual",
"approvers": [
"$appeal.creator.manager_email"
]
},
{
"name": "resource_owner_approval",
"description": "Approval from resource admin/owner",
"strategy": "manual",
"approvers": [
"$appeal.resource.details.owner"
]
}
]
}'

Listing Policies

To get the list of all the policies created by the user, use the GET Method on {{HOST}}/api/v1beta1/policies

Responses
CodeDescriptionType
200A successful response.[Policy]
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request GET '{{HOST}}/api/v1beta1/policies'

Viewing Policies

Viewing a policy can be done by the GET Method on {{HOST}}/api/v1beta1/policies/:id/versions/:version

Parameters
NameLocated inDescriptionRequiredType
idpathPolicy unique identifierYesstring
versionpathPolicy versionYesuint32
Responses
CodeDescriptionType
200A successful response.Policy
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request GET '{{HOST}}/api/v1beta1/policies/{{policy_id}}/versions/{{policy_version}}'

Managing Providers

Provider manages roles, resources, provider credentials and also points each resource type to a considered policy.

Registering Providers

Once a provider config is registered, Guardian will immediately fetch the resources and store it in the database.

Providers can be created by calling to POST Method {{HOST}}/api/v1beta1/providers

Parameters
NameLocated inDescriptionRequiredType
bodybodyProvider config dataYesProviderConfig
Responses
CodeDescriptionType
200A successful response.ProviderResponse
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request POST '{{HOST}}/api/v1beta1/providers' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "bigquery",
"urn": "gcp-project-id-bigquery",
"allowed_account_types": [
"user",
"serviceAccount"
],
"credentials": {
"service_account_key": "{{base64 encoded service account key json}}",
"resource_name": "projects/gcp-project-id"
},
"appeal": {
"allow_permanent_access": false,
"allow_active_access_extension_in": "168h"
},
"resources": [
{
"type": "dataset",
"policy": {
"id": "my_policy",
"version": 1
},
"roles": [
{
"id": "viewer",
"name": "Viewer",
"permissions": [
"READER"
]
},
{
"id": "editor",
"name": "Editor",
"permissions": [
"WRITER"
]
}
]
},
{
"type": "table",
"policy": {
"id": "my_policy",
"version": 1
},
"roles": [
{
"id": "viewer",
"name": "Viewer",
"permissions": [
"roles/bigquery.dataViewer"
]
},
{
"id": "editor",
"name": "Editor",
"permissions": [
"roles/bigquery.dataEditor"
]
}
]
}
]
}'

Check provider reference for more details on Provider schema.

Updating Providers

Providers can be updated by calling to PUT Method {HOST}}/api/v1beta1/providers/:id

Parameters
NameLocated inDescriptionRequiredType
idpathUnique identifier of the provider to be updatedYesString
bodybodyProvider config update payloadYesProviderConfig
Responses
CodeDescriptionType
200A successful response.ProviderResponse
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request PUT '{{HOST}}/api/v1beta1/providers/{{provider_id}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"allowed_account_types": [
"user"
]
}'

Listing Providers

To get the list of all the providers avaliable, call the GET Method on {{HOST}}/api/v1beta1/providers

Responses
CodeDescriptionType
200A successful response.[ProviderResponse]
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request GET '{{HOST}}/api/v1beta1/providers'

Viewing Providers

To see the details of a particular provider by id, call the GET Method on {{HOST}}/api/v1beta1/providers/:id with the following parameters:

Parameters
NameLocated inDescriptionRequiredType
idpathYesString
Responses
CodeDescriptionType
200A successful response.ProviderResponse
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request GET '{{HOST}}/api/v1beta1/providers/{{provider_id}}'

Delete Provider

To delete a particular provider from the database use the DELETE Method on {{HOST}}/api/v1beta1/providers/:id with the parameters as shown here:

Parameters
NameLocated inDescriptionRequiredType
idpathYesString
Response
CodeDescriptionType
200A successful response.NIL
defaultAn unexpected error response.rpcStatus

Listing Roles for a Resource Type

Listing roles can be done by calling to GET Method {{HOST}}/api/v1beta1/providers/:id/resources/:resource_type/roles

Parameters
NameLocated inDescriptionRequiredType
idpathYesstring
resource_typepathYesstring
Responses
CodeDescriptionType
200A successful response.[Role]
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request GET '{{HOST}}/api/v1beta1/providers/{{provider_id}}/resources/{{resource_type}}/roles'

Managing Resources

Resource in Guardian represents the actual resource in the provider e.g. for BigQuery provider, a resource represents a dataset or a table. One of Guardian's responsibility is to manage the access to resources, and in order to do that Guardian needs to be able to manage the resources as well.

Listing Resources

To get the list of all the resources available, call the GET Method on {{HOST}}/api/v1beta1/resources

Query Parameters
NameLocated inDescriptionRequiredType
provider_typequeryUnique Provider name

Enum:
- bigquery , gcs , gcloud_iam , metabase , grafana , tableau , noop
Nostring
provider_urnqueryUnique provider URNNostring
typequeryUnique resource name

Enum:
- dataset , table for the BigQuery
- folder , dashboard for the Grafana
- project , organization for the Gcloud IAM
- workbook , view , metric , datasource , flow for Tableau
- bucket for Google Cloud Storage
- database , table , collection , group for Metabase
Nostring
urnqueryUnique Resource URNNostring
namequeryUnique Resource NameNostring
detailsqueryNo[string]
is_deletedquerySet to query for resources which have been deletedNobool
Responses
CodeDescriptionType
200A successful response.[Resource]
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request GET '{{HOST}}/api/v1beta1/resources'

Viewing Resources

To see the details of a particular resource by id, call the GET Method on {{HOST}}/api/v1beta1/resources/:id using the following parameters:

Parameters
NameLocated inDescriptionRequiredType
idpathUnique Resource IdentifierYesString
Responses
CodeDescriptionType
200A successful response.Resource
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request GET '{{HOST}}/api/v1beta1/resources/{{resource_id}}'

Update Resources

Guardian allows users to add metadata to the resources. This can be useful when configuring the approval steps in the policy that needs information from metadata e.g. “owners” as the approvers.

Update a resource can be done by calling to PUT Method {{HOST}}/api/v1beta1/resources/:id

Parameters
NameLocated inDescriptionRequiredType
idpathUnique Resource IdentifierYesString
bodybodyYesResource
Responses
CodeDescriptionType
200A successful response.Resource
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request PUT '{{HOST}}/api/v1beta1/resources/{{resource_id}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"details": {
"key1": "value1",
"key2": "value2"
}
}'

Delete Resource

To delete a particular provider from the database use the DELETE Method on {{HOST}}/api/v1beta1/resources/:id with the parameters as shown here:

Parameters
NameLocated inDescriptionRequiredType
idpathUnique Resource IdentifierYesString
Response
CodeDescriptionType
200A successful response.NIL
defaultAn unexpected error response.rpcStatus

Managing Appeals

An appeal is essentially a request created by users to give them access to resources. In order to grant the access, an appeal has to be approved by approvers which is assigned based on the applied policy. Appeal contains information about the requested account, the creator, the selected resources, the specific role for accessing the resource, and options to determine the behaviour of the access e.g. permanent or temporary access.

Create Appeal

Guardian creates access for users to resources with configurable approval flow. Appeal created by user with specifying which resource they want to access and also the role.

Appeals can be created by calling the POST Method on {{HOST}}/api/v1beta1/appeals using the following parameters:

Parameters
NameLocated inDescriptionRequiredType
bodybodyContains account id and type of the user creating appeal.
It also contains a list of resources for which request is created
YesAppeal Request
X-Auth-EmailheaderContains the user email creating the appealYesstring
Responses
CodeDescriptionType
200A successful response.Appeal
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request POST '{{HOST}}/api/v1beta1/appeals' \
--header 'X-Auth-Email: user@example.com' \
--header 'Content-Type: application/json' \
--data-raw '{
"account_id": "user@example.com",
"resources": [
{
"id": "a32b702a-029d-4d76-90c4-c3b8cc52941b",
"role": "viewer"
}
]
}'

List Appeals

To get the list of all appeals with addtional queries on the result, use the GET Method on {{HOST}}/api/v1beta1/appeals The request parameters associated with this is API are as follows:

Parameters
NameLocated inDescriptionRequiredType
account_idquerythis will be depcreate use account_idsNostring
account_idsqueryNo[string]
statusesqueryEnum: pending , rejected , active , terminated , cancelledNo[string]
rolequeryNostring
provider_typesqueryEnum:
- bigquery , gcs , gcloud_iam , metabase , grafana , tableau , noop
No[string]
provider_urnsqueryNo[string]
resource_typesqueryNo[string]
resource_urnsqueryNo[string]
order_byqueryNo[string]
created_byqueryEmail of the appeal creatorNostring
Responses
CodeDescriptionType
200A successful response.[Appeal]
defaultAn unexpected error response.rpcStatus

List User Appeal

To get the list of all the appeals by the current user, use the GET Method on {{HOST}}/api/v1beta1/me/appeals The request parameters associated with this is API are as follows:

Parameters
NameLocated inDescriptionRequiredType
statusesqueryEnum: pending , rejected , active , terminated , cancelledNo[string]
rolequeryNostring
provider_typesqueryEnum:
- bigquery , gcs , gcloud_iam , metabase , grafana , tableau , noop
No[string]
provider_urnsqueryNo[string]
resource_typesqueryNo[string]
resource_urnsqueryNo[string]
order_byqueryNo[string]
X-Auth-EmailheaderContains the user email who is requesting for the list of all its appealsYesstring
Responses
CodeDescriptionType
200A successful response.[Appeal]
defaultAn unexpected error response.rpcStatus

Get Appeal

To get a particular appeal by its id use the GET Method on {{HOST}}/api/v1beta1/appeals/{id} using the parameters given below:

Parameters
NameLocated inDescriptionRequiredType
idpathUnique Identifier for the AppealYesstring
Responses
CodeDescriptionType
200A successful response.Appeal
defaultAn unexpected error response.rpcStatus

Revoke Access

Access to a resource by a user can be revoked by calling the PUT Method on {{HOST}}/api/v1beta1/appeals/{id}/revoke using the following parameters:

Parameters
NameLocated inDescriptionRequiredType
idpathUnique Identifier for the AppealYesstring
reasonbodyContains the reason of revoking the accessNostring
X-Auth-EmailheaderContains the user/service account email of the person revoking the accessYesstring
Responses
CodeDescriptionType
200A successful response.Appeal
defaultAn unexpected error response.rpcStatus

Canceling Appeals

Appeal creator can cancel their appeal while it's status is still on pending.

Appeals can be canceled by calling the PUT Method on {{HOST}}/api/v1beta1/appeals/:id/cancel endpoint using the following parameters:

Parameters
NameLocated inDescriptionRequiredType
idpathUnique Identifier for the AppealYesString
Responses
CodeDescriptionType
200A successful response.Appeal
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request PUT '{{HOST}}/api/v1beta1/appeals/{{appeal_id}}/cancel'

Bulk Revoke Access

Bulk revoke of active resource-accesses based on parameters by calling the POST Method on {{HOST}}/api/v1beta1/appeals/revoke using the following parameters:

Parameters
NameLocated inDescriptionRequiredType
account_idsqueryNo[string]
provider_typesqueryEnum:
- bigquery , gcs , gcloud_iam , metabase , grafana , tableau , noop
No[string]
provider_urnsqueryNo[string]
resource_typesqueryNo[string]
resource_urnsqueryNo[string]
reasonqueryNostring
X-Auth-EmailheaderContains the user email who is requesting to bulk revoke of accessYesstring
Responses
CodeDescriptionType
200A successful response.[]Appeal
defaultAn unexpected error response.rpcStatus

Here is an example below:

$ curl --request PUT '{{HOST}}/api/v1beta1/appeals/{{appeal_id}}/cancel'
$ curl --request POST 'localhost:3000/api/v1beta1/appeals/revoke'
--header 'X-Auth-Email: abc@xyz.com'
--header 'Content-Type: application/json'
--data-raw '{
"account_id":["user1.@domain1.com", "user2.@domain1.com"],
"reason": "Bulk revoke"
}'

List Approvals

To get the list of all approvals, use the GET Method on {{HOST}}/api/v1beta1/approvals using the following parameters as given below:

Parameters
NameLocated inDescriptionRequiredType
account_idqueryNostring
statusesqueryEnum: pending , rejected , active , terminated , cancelledNo[string]
order_byqueryNo[string]
created_byqueryNostring
sizequeryNoint
offsetqueryNoint
Response
CodeDescriptionType
200A successful response.[Approval]
defaultAn unexpected error response.rpcStatus

List User Approvals

To get the list of all approvals for the current user, use the GET Method on {{HOST}}/api/v1beta1/me/approvals using the following parameters as given below:

Parameters
NameLocated inDescriptionRequiredType
account_idqueryNostring
statusesqueryEnum: pending , rejected , active , terminated , cancelledNo[string]
order_byqueryNo[string]
X-Auth-EmailheaderContains the user/service account email used for authorizationYesstring
Response
CodeDescriptionType
200A successful response.[Approval]
defaultAn unexpected error response.rpcStatus

Update Approval (Approving and Rejecting Appeals)

Appeals can be approved/rejected by calling the POST Method on {{HOST}}/api/v1beta1/appeals/:id/approvals/:approval_name endpoint with the following parameters:

Parameters
NameLocated inDescriptionRequiredType
idpathUnique Identifier for the AppealYesString
approval_namepathName of the approval step.

For instance resource_owner_approval or admin_approval
in this Example
YesString
actionbodyAction which the approver wants to take(Approve or Reject)YesObject(Action)
X-Auth-EmailheaderContains the approver's email idYesstring
Responses
CodeDescriptionType
200A successful response.Appeal
defaultAn unexpected error response.rpcStatus

Here is an example below:

Approve an Appeal

$ curl --request POST '{{HOST}}/api/v1beta1/appeals/{{appeal_id}}/approvals/{{approval_step_name}}' \
--header 'X-Auth-Email: user@example.com' \
--header 'Content-Type: application/json' \
--data-raw '{
"action": "approve"
}'

Reject an Appeal

$ curl --request POST '{{HOST}}/api/v1beta1/appeals/{{appeal_id}}/approvals/{{approval_step_name}}' \
--header 'X-Auth-Email: user@example.com' \
--header 'Content-Type: application/json' \
--data-raw '{
"action": "reject",
"reason": "{{rejection_message}}"
}'

Add Approver

Approver can be added by calling POST /api/v1beta1/appeals/:appeal_id/approvals/:approval_id/approvers endpoint with the following parameters:

Parameters
NameLocated inDescriptionRequiredType
appeal_idpathUnique identifier of the appealYesstring(UUID)
approval_idpathUnique identifier or name of the approvalYesstring(UUID) or string
emailbodyNew approver emailYesObject(AddApproverRequest)

Example:

$ curl --location --request POST '{{HOST}}/api/v1beta1/appeals/{{appeal_id}}/approvals/{{approval_id}}/approvers' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "new.approver@example.com"
}'
Responses
CodeDescriptionType
200A successful response.AddApproverResponse
defaultAn unexpected error response.rpcStatus

Delete Approver

Existing approver can be removed by calling DELETE /api/v1beta1/appeals/:appeal_id/approvals/:approval_id/approvers/:email endpoint with the following parameters:

Parameters
NameLocated inDescriptionRequiredType
appeal_idpathUnique identifier of the appealYesstring(UUID)
approval_idpathUnique identifier or name of the approvalYesstring(UUID) or string
emailpathTo be deleted approver emailYesstring

Example:

$ curl --location --request DELETE '{{HOST}}/api/v1beta1/appeals/{{appeal_id}}/approvals/{{approval_id}}/approvers/{{email}}'
Responses
CodeDescriptionType
200A successful response.DeleteApproverResponse
defaultAn unexpected error response.rpcStatus

Models

rpcStatus

NameTypeDescriptionRequired
codeintegerThe status code, which should be an enum value of google.rpc.CodeNo
messagestringA developer-facing error message, which should be in English.
Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.
No
details[protobufAny]A list of messages that carry the error details.
There is a common set of message types for APIs to use.
No

protobufAny

NameTypeDescriptionRequired
typeUrlstringA URL/resource name whose content describes the type of the serialized messageNo
valuebyteMust be valid serialized data of the above specified type.No

providerResponse

NameTypeDescription
idstringUnique identifier for the Provider
TypestringName of the Provider type.

Possible values: bigquery, metabase, tableau, gcloud_iam, grafana
URNstringProvider instance identifier
Configobject(Provider Config)Contains the credentials, provider type and URN, allowed account types and other info about the Provider
CreatedAtdateTimeTimestamp when the resource is created.
UpdatedAtdateTimeTimestamp when the resource was last updated

Appeal Request Config

NameTypeDescription
idstringUser/Service Account Email creating the appeal
account_type[string]Contains the allowed account type for the provider.
For example, the possible values for BigQuery Provider and Google Cloud IAM is user and serviceAccount
resources[Object(Resource)]List of resource objects

Resource

NameTypeDescription
idstring
rolestringRole to be assigned. Can be Viewer, Editor, Admin depending on the Provider
optionsObject (Appeal Options)
detailsobjectAdditional information for the appeal. Details can be added from the appeal creation.

AppealOptions

NameTypeDescription
expiration_datedateTimeTimestamp when the appeal expires
durationstringDuration of the access to the resource

Action

NameTypeDescription
actionstringCan be Approve or Reject the Appeal
reasonstringIn case an appeal is rejected, the reason is to be updated in this field

AddApproverRequest

NameTypeDescription
emailstringEmail address of the new approver

AddApproverResponse

NameTypeDescription
appealObject(Appeal)Appeal object

DeleteApproverResponse

NameTypeDescription
appealObject(Appeal)Appeal object