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

Name	Located in	Description	Required	Type
body	body	Contains a policy name, steps for approval flow, External identity manager(IAM) details for authorization required for the accessing the resource	Yes	Policy
X-Auth-Email	header	Contains the user/service account email used for authorization	Yes	string

Responses

Code	Description	Type
200	A successful response	Policy
default	An 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

Name	Located in	Description	Required	Type
id	path	Unique identifier for policy to be updated	Yes	String
body	body	Contains the fields reuired to be added/updated in the policy	Yes	Policy

Responses

Code	Description	Type
200	A successful response.	Policy
default	An 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

Code	Description	Type
200	A successful response.	[Policy]
default	An 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

Name	Located in	Description	Required	Type
id	path	Policy unique identifier	Yes	string
version	path	Policy version	Yes	uint32

Responses

Code	Description	Type
200	A successful response.	Policy
default	An 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

Name	Located in	Description	Required	Type
body	body	Provider config data	Yes	ProviderConfig

Responses

Code	Description	Type
200	A successful response.	ProviderResponse
default	An 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

Name	Located in	Description	Required	Type
id	path	Unique identifier of the provider to be updated	Yes	String
body	body	Provider config update payload	Yes	ProviderConfig

Responses

Code	Description	Type
200	A successful response.	ProviderResponse
default	An 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

Code	Description	Type
200	A successful response.	[ProviderResponse]
default	An 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

Name	Located in	Description	Required	Type
id	path		Yes	String

Responses

Code	Description	Type
200	A successful response.	ProviderResponse
default	An 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

Name	Located in	Description	Required	Type
id	path		Yes	String

Response

Code	Description	Type
200	A successful response.	NIL
default	An 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

Name	Located in	Description	Required	Type
id	path		Yes	string
resource_type	path		Yes	string

Responses

Code	Description	Type
200	A successful response.	[Role]
default	An 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

Name	Located in	Description	Required	Type
provider_type	query	Unique Provider name Enum: - `bigquery` , `gcs` , `gcloud_iam` , `metabase` , `grafana` , `tableau` , `noop`	No	string
provider_urn	query	Unique provider URN	No	string
type	query	Unique 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	No	string
urn	query	Unique Resource URN	No	string
name	query	Unique Resource Name	No	string
details	query		No	[string]
is_deleted	query	Set to query for resources which have been deleted	No	bool

Responses

Code	Description	Type
200	A successful response.	[Resource]
default	An 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

Name	Located in	Description	Required	Type
id	path	Unique Resource Identifier	Yes	String

Responses

Code	Description	Type
200	A successful response.	Resource
default	An 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

Name	Located in	Description	Required	Type
id	path	Unique Resource Identifier	Yes	String
body	body		Yes	Resource

Responses

Code	Description	Type
200	A successful response.	Resource
default	An 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

Name	Located in	Description	Required	Type
id	path	Unique Resource Identifier	Yes	String

Response

Code	Description	Type
200	A successful response.	NIL
default	An 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

Name	Located in	Description	Required	Type
body	body	Contains account id and type of the user creating appeal. It also contains a list of resources for which request is created	Yes	Appeal Request
X-Auth-Email	header	Contains the user email creating the appeal	Yes	string

Responses

Code	Description	Type
200	A successful response.	Appeal
default	An 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

Name	Located in	Description	Required	Type
account_id	query	this will be depcreate use `account_ids`	No	string
account_ids	query		No	[string]
statuses	query	Enum: `pending` , `rejected` , `active` , `terminated` , `cancelled`	No	[string]
role	query		No	string
provider_types	query	Enum: - `bigquery` , `gcs` , `gcloud_iam` , `metabase` , `grafana` , `tableau` , `noop`	No	[string]
provider_urns	query		No	[string]
resource_types	query		No	[string]
resource_urns	query		No	[string]
order_by	query		No	[string]
created_by	query	Email of the appeal creator	No	string

Responses

Code	Description	Type
200	A successful response.	[Appeal]
default	An 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

Name	Located in	Description	Required	Type
statuses	query	Enum: `pending` , `rejected` , `active` , `terminated` , `cancelled`	No	[string]
role	query		No	string
provider_types	query	Enum: - `bigquery` , `gcs` , `gcloud_iam` , `metabase` , `grafana` , `tableau` , `noop`	No	[string]
provider_urns	query		No	[string]
resource_types	query		No	[string]
resource_urns	query		No	[string]
order_by	query		No	[string]
X-Auth-Email	header	Contains the user email who is requesting for the list of all its appeals	Yes	string

Responses

Code	Description	Type
200	A successful response.	[Appeal]
default	An 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

Name	Located in	Description	Required	Type
id	path	Unique Identifier for the Appeal	Yes	string

Responses

Code	Description	Type
200	A successful response.	Appeal
default	An 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

Name	Located in	Description	Required	Type
id	path	Unique Identifier for the Appeal	Yes	string
reason	body	Contains the reason of revoking the access	No	string
X-Auth-Email	header	Contains the user/service account email of the person revoking the access	Yes	string

Responses

Code	Description	Type
200	A successful response.	Appeal
default	An 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

Name	Located in	Description	Required	Type
id	path	Unique Identifier for the Appeal	Yes	String

Responses

Code	Description	Type
200	A successful response.	Appeal
default	An 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

Name	Located in	Description	Required	Type
account_ids	query		No	[string]
provider_types	query	Enum: - `bigquery` , `gcs` , `gcloud_iam` , `metabase` , `grafana` , `tableau` , `noop`	No	[string]
provider_urns	query		No	[string]
resource_types	query		No	[string]
resource_urns	query		No	[string]
reason	query		No	string
X-Auth-Email	header	Contains the user email who is requesting to bulk revoke of access	Yes	string

Responses

Code	Description	Type
200	A successful response.	[]Appeal
default	An 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

Name	Located in	Description	Required	Type
account_id	query		No	string
statuses	query	Enum: `pending` , `rejected` , `active` , `terminated` , `cancelled`	No	[string]
order_by	query		No	[string]
created_by	query		No	string

Response

Code	Description	Type
200	A successful response.	[Approval]
default	An 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

Name	Located in	Description	Required	Type
account_id	query		No	string
statuses	query	Enum: `pending` , `rejected` , `active` , `terminated` , `cancelled`	No	[string]
order_by	query		No	[string]
X-Auth-Email	header	Contains the user/service account email used for authorization	Yes	string

Response

Code	Description	Type
200	A successful response.	[Approval]
default	An 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

Name	Located in	Description	Required	Type
id	path	Unique Identifier for the Appeal	Yes	String
approval_name	path	Name of the approval step. For instance `resource_owner_approval` or `admin_approval` in this Example	Yes	String
action	body	Action which the approver wants to take(`Approve` or `Reject`)	Yes	Object(Action)
X-Auth-Email	header	Contains the approver's email id	Yes	string

Responses

Code	Description	Type
200	A successful response.	Appeal
default	An 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

Name	Located in	Description	Required	Type
appeal_id	path	Unique identifier of the appeal	Yes	string(UUID)
approval_id	path	Unique identifier or name of the approval	Yes	string(UUID) or string
email	body	New approver email	Yes	Object(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

Code	Description	Type
200	A successful response.	AddApproverResponse
default	An 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

Name	Located in	Description	Required	Type
appeal_id	path	Unique identifier of the appeal	Yes	string(UUID)
approval_id	path	Unique identifier or name of the approval	Yes	string(UUID) or string
email	path	To be deleted approver email	Yes	string

Example:

$ curl --location --request DELETE '{{HOST}}/api/v1beta1/appeals/{{appeal_id}}/approvals/{{approval_id}}/approvers/{{email}}'

Responses

Code	Description	Type
200	A successful response.	DeleteApproverResponse
default	An unexpected error response.	rpcStatus

Models

rpcStatus

Name	Type	Description	Required
code	integer	The status code, which should be an enum value of google.rpc.Code	No
message	string	A 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

Name	Type	Description	Required
typeUrl	string	A URL/resource name whose content describes the type of the serialized message	No
value	byte	Must be valid serialized data of the above specified type.	No

providerResponse

Name	Type	Description
id	string	Unique identifier for the Provider
Type	string	Name of the Provider type. Possible values: `bigquery`, `metabase`, `tableau`, `gcloud_iam`, `grafana`
URN	string	Provider instance identifier
Config	object(Provider Config)	Contains the credentials, provider type and URN, allowed account types and other info about the Provider
CreatedAt	dateTime	Timestamp when the resource is created.
UpdatedAt	dateTime	Timestamp when the resource was last updated

Appeal Request Config

Name	Type	Description
id	string	User/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

Name	Type	Description
id	string
role	string	Role to be assigned. Can be `Viewer`, `Editor`, `Admin` depending on the Provider
options	Object (Appeal Options)
details	object	Additional information for the appeal. Details can be added from the appeal creation.

AppealOptions

Name	Type	Description
expiration_date	dateTime	Timestamp when the appeal expires
duration	string	Duration of the access to the resource

Action

Name	Type	Description
action	string	Can be `Approve` or `Reject` the Appeal
reason	string	In case an appeal is rejected, the reason is to be updated in this field

AddApproverRequest

Name	Type	Description
email	string	Email address of the new approver

AddApproverResponse

Name	Type	Description
appeal	Object(Appeal)	Appeal object

DeleteApproverResponse

Name	Type	Description
appeal	Object(Appeal)	Appeal object

API

Managing Policies​

Create Policy​

Parameters​

Responses​

Updating Policy​

Parameters​

Responses​

Listing Policies​

Responses​

Viewing Policies​

Parameters​

Responses​

Managing Providers​

Registering Providers​

Parameters​

Responses​

Updating Providers​

Parameters​

Responses​

Listing Providers​

Responses​

Viewing Providers​

Parameters​

Responses​

Delete Provider​

Parameters​

Response​

Listing Roles for a Resource Type​

Parameters​

Responses​

Managing Resources​

Listing Resources​

Query Parameters​

Responses​

Viewing Resources​

Parameters​

Responses​

Update Resources​

Parameters​

Responses​

Delete Resource​

Parameters​

Response​

Managing Appeals​

Create Appeal​

Parameters​

Responses​

List Appeals​

Parameters​

Responses​

List User Appeal​

Parameters​

Responses​

Get Appeal​

Parameters​

Responses​

Revoke Access​

Parameters​

Responses​

Canceling Appeals​

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

Parameters​

Responses​

Bulk Revoke Access​

Parameters​

Responses​

List Approvals​

Parameters​

Response​

List User Approvals​

Parameters​

Response​

Update Approval (Approving and Rejecting Appeals)​

Parameters​

Responses​

Approve an Appeal​

Reject an Appeal​

Add Approver​

Parameters​

Managing Policies

Create Policy

Parameters

Responses

Updating Policy

Parameters

Responses

Listing Policies

Responses

Viewing Policies

Parameters

Responses

Managing Providers

Registering Providers

Parameters

Responses

Updating Providers

Parameters

Responses

Listing Providers

Responses

Viewing Providers

Parameters

Responses

Delete Provider

Parameters

Response

Listing Roles for a Resource Type

Parameters

Responses

Managing Resources

Listing Resources

Query Parameters

Responses

Viewing Resources

Parameters

Responses

Update Resources

Parameters

Responses

Delete Resource

Parameters

Response

Managing Appeals

Create Appeal

Parameters

Responses

List Appeals

Parameters

Responses

List User Appeal

Parameters

Responses

Get Appeal

Parameters

Responses

Revoke Access

Parameters

Responses

Canceling Appeals

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

Parameters

Responses

Bulk Revoke Access

Parameters

Responses

List Approvals

Parameters

Response

List User Approvals

Parameters

Response

Update Approval (Approving and Rejecting Appeals)

Parameters

Responses

Approve an Appeal

Reject an Appeal

Add Approver

Parameters

Responses