---
title: "Access Policy"
description: "Explore our comprehensive Access Policy documentation for creating, managing, and updating policy instances within your platform. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/reference/types/accessPolicy"
---

# <a id="top"></a>Access Policy

An Object

1.  [Platform](/documentation/gitana/4.0/reference/types/platform.md)
2.  [Access Policy](/documentation/gitana/4.0/reference/types/accessPolicy.md)

##### Table of Contents

- [Overview](#top "Overview")
- [Parent](#parent "Parent")
- [Properties](#properties "Properties")
- [Methods](#methods "Methods")
- [Schema](#schema "Schema")

> **Note:** Drop in one of our language drivers to accelerate your development.  
> Here are links to some of our popular [Cookbooks](/documentation/gitana/4.0/developers/cookbooks/overview.md) to help you get started!
> 
> - [C#](/documentation/gitana/4.0/developers/cookbooks/csharp.md)
> - [Go](/documentation/gitana/4.0/developers/cookbooks/go.md)
> - [Java](/documentation/gitana/4.0/developers/cookbooks/java.md)
> - [JavaScript](/documentation/gitana/4.0/developers/cookbooks/javascript2.md)
> - [PHP](/documentation/gitana/4.0/developers/cookbooks/php.md)
> - [Python](/documentation/gitana/4.0/developers/cookbooks/python.md)
> - [Ruby](/documentation/gitana/4.0/developers/cookbooks/ruby.md)

## <a id="parent"></a>Parent

This Access Policy is contained within a [Platform](/documentation/gitana/4.0/reference/types/platform.md).

## <a id="properties"></a>Properties

The following properties are available:

| Property | Type | Default | Read-Only | Description |
| --- | --- | --- | --- | --- |
| \_doc | string |  | No | The primary ID |
| \_system | object |  | No | Metadata maintained by the system |
| order | string |  | No |  |
| scope | string |  | No |  |
| statements | array |  | No |  |

## <a id="methods"></a>Methods

The following methods are available:

- [Assign Policy](#post-access-policies-accesspolicyid-assign "Assign Policy")
- [Check Permission](#post-access-policies-accesspolicyid-permissions-permissionid-check "Check Permission")
- [Check Single Authority](#post-access-policies-accesspolicyid-authorities-authorityid-check "Check Single Authority")
- [Check multiple Authorities](#post-access-policies-authorities-check "Check multiple Authorities")
- [Check multiple Permissions](#post-access-policies-permissions-check "Check multiple Permissions")
- [Collect Policies](#post-access-policies-collect "Collect Policies")
- [Conditions Access](#get-access-conditions "Conditions Access")
- [Create Access Policy](#post-access-policies "Create Access Policy")
- [Delete Access Policy](#delete-access-policies-accesspolicyid "Delete Access Policy")
- [Delete Access Policy](#post-access-policies-accesspolicyid-delete "Delete Access Policy")
- [Export Access Policy](#post-access-policies-accesspolicyid-export "Export Access Policy")
- [Find Policies](#post-access-policies-find "Find Policies")
- [Finds all of the resources that are assigned targets of this access policy. The targets are returned as references which identify resources that are bestowed the grants and revokes indicated by the policy. The targets are generally Users, Groups or Teams.](#get-access-policies-accesspolicyid-targets "Finds all of the resources that are assigned targets of this access policy. The targets are returned as references which identify resources that are bestowed the grants and revokes indicated by the policy. The targets are generally Users, Groups or Teams.")
- [Grant Authority](#post-access-policies-accesspolicyid-authorities-authorityid-grant "Grant Authority")
- [Import Access Policy](#post-access-policies-accesspolicyid-import "Import Access Policy")
- [List Access Policy Templates](#get-access-policies-templates "List Access Policy Templates")
- [List System Access Policies](#get-access-policies-system "List System Access Policies")
- [Lists Access Policy](#get-access-policies "Lists Access Policy")
- [Queries for Access Policy](#post-access-policies-query "Queries for Access Policy")
- [Read ACL](#get-access-policies-accesspolicyid-acl-list "Read ACL")
- [Read ACL for Principal](#get-access-policies-accesspolicyid-acl "Read ACL for Principal")
- [Read Access Policy](#get-access-policies-accesspolicyid "Read Access Policy")
- [Read Access Policy Template](#get-access-policies-templates-templatekey "Read Access Policy Template")
- [Read Authorities Report](#post-access-policies-accesspolicyid-authorities "Read Authorities Report")
- [Read System Access Policy](#get-access-policies-system-key "Read System Access Policy")
- [Revoke Authority](#post-access-policies-accesspolicyid-authorities-authorityid-revoke "Revoke Authority")
- [Unassign Policy](#post-access-policies-accesspolicyid-unassign "Unassign Policy")
- [Unassignall Policies](#post-access-policies-unassignall "Unassignall Policies")
- [Update Access Policy](#put-access-policies-accesspolicyid "Update Access Policy")
- [Update Access Policy](#post-access-policies-accesspolicyid-update "Update Access Policy")

### <a id="post-access-policies-accesspolicyid-assign"></a>Assign Policy

POST /access/policies/{accessPolicyId}/assign

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| ref | true | string |  |

### <a id="post-access-policies-accesspolicyid-permissions-permissionid-check"></a>Check Permission

Checks whether one or more authorities against the specified accessPolicy are granted for a given set of users

POST /access/policies/{accessPolicyId}/permissions/{permissionId}/check

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| permissionId | true | string | The ID of the permission |
| id | true | string |  |

#### Response

```json
{
  "$ref": "#/components/schemas/checkPermission"
}
```

### <a id="post-access-policies-accesspolicyid-authorities-authorityid-check"></a>Check Single Authority

Checks whether a single authority is granted against the specified accessPolicy for the given user

POST /access/policies/{accessPolicyId}/authorities/{authorityId}/check

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| authorityId | true | string | The ID or authority key for the authority |
| id | true | string |  |

#### Response

```json
{
  "type": "object",
  "description": "Check",
  "extends": "status",
  "properties": {
    "check": {
      "type": "boolean"
    },
    "ok": null
  }
}
```

### <a id="post-access-policies-authorities-check"></a>Check multiple Authorities

Checks whether one or more authorities against the specified accessPolicy are granted for a given set of users

POST /access/policies/authorities/check

#### Parameters

This function has no parameters.

#### Response

```json
{
  "type": "object",
  "description": "Check Multiple Authorities Out",
  "properties": {
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "permissionedId": {
            "type": "string"
          },
          "principalId": {
            "type": "string"
          },
          "authorityId": {
            "type": "string"
          },
          "result": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

### <a id="post-access-policies-permissions-check"></a>Check multiple Permissions

Checks whether one or more permissions against the specified accessPolicy are granted for a given set of users

POST /access/policies/permissions/check

#### Parameters

This function has no parameters.

#### Response

```json
{
  "type": "object",
  "description": "Check Multiple Permissions Out",
  "properties": {
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "permissionedId": {
            "type": "string"
          },
          "principalId": {
            "type": "string"
          },
          "permissionId": {
            "type": "string"
          },
          "result": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

### <a id="post-access-policies-collect"></a>Collect Policies

POST /access/policies/collect

#### Parameters

This function has no parameters.

### <a id="get-access-conditions"></a>Conditions Access

GET /access/conditions

#### Parameters

This function has no parameters.

### <a id="post-access-policies"></a>Create Access Policy

Creates a new Access Policy

POST /access/policies

#### Parameters

This function has no parameters.

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indicates whether the operation succeeded or not"
    }
  }
}
```

### <a id="delete-access-policies-accesspolicyid"></a>Delete Access Policy

Deletes an existing Access Policy

DELETE /access/policies/{accessPolicyId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indicates whether the operation succeeded or not"
    }
  }
}
```

### <a id="post-access-policies-accesspolicyid-delete"></a>Delete Access Policy

Deletes an existing Access Policy

POST /access/policies/{accessPolicyId}/delete

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indicates whether the operation succeeded or not"
    }
  }
}
```

### <a id="post-access-policies-accesspolicyid-export"></a>Export Access Policy

Starts an export job for this resource

POST /access/policies/{accessPolicyId}/export

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| groupId | false | string | The Group ID to be assigned to the exported archive |
| artifactId | false | string | The Artifact ID to be assigned to the exported archive |
| versionId | false | string | The Version ID to be assigned to the exported archive |
| vaultId | false | string | The ID of the vault where the exported archive should be saved |
| schedule | false | string | Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous') |

#### Response

```json
{
  "type": "object",
  "description": "Export Configuration",
  "properties": {
    "startDate": {
      "type": "object",
      "description": "Only include objects whose modification date is after this time (epoch millis). This is used for partial or rolling exports."
    },
    "endDate": {
      "type": "object",
      "description": "Only include objects whose modification date is before this time (epoch millis). This is used for partial or rolling exports."
    },
    "startChangeset": {
      "type": "string",
      "description": "Only include data that is relevant to changesets at or beyond the specified changeset."
    },
    "endChangeset": {
      "type": "string",
      "description": "Only include data that is relevant to changesets at or before the specified changeset."
    },
    "includeACLs": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include ACLs during export."
    },
    "includeTeams": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Teams during export."
    },
    "includeActivities": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Activities during export."
    },
    "includeBinaries": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Binaries for data stores during export."
    },
    "includeAttachments": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Attachments for Attachables during export."
    },
    "artifactDependencies": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "artifactIncludes": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "forceIncludes": {
      "type": "boolean"
    }
  }
}
```

### <a id="post-access-policies-find"></a>Find Policies

POST /access/policies/find

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| ref | true | string |  |
| scope | false | string |  |

### <a id="get-access-policies-accesspolicyid-targets"></a>Finds all of the resources that are assigned targets of this access policy. The targets are returned as references which identify resources that are bestowed the grants and revokes indicated by the policy. The targets are generally Users, Groups or Teams.

List the assigned targets

GET /access/policies/{accessPolicyId}/targets

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| sort | false | object | Defines how to sort fields in the result set |
| skip | false | number | Skips the result set cursor ahead the specified number of records |
| limit | false | number | Specifies the number of records to be handed back in the result set |

This method supports pagination.

#### Response

```json
{
  "type": "object",
  "description": "Result Map",
  "properties": {
    "total_rows": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "size": {
      "type": "number"
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/resultmap_accessPolicy"
      }
    }
  }
}
```

#### Examples

### <a id="post-access-policies-accesspolicyid-authorities-authorityid-grant"></a>Grant Authority

Grants an authority against the specified accessPolicy to a given user

POST /access/policies/{accessPolicyId}/authorities/{authorityId}/grant

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| authorityId | true | string | The ID or authority key for the authority |
| id | true | string |  |

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indicates whether the operation succeeded or not"
    }
  }
}
```

### <a id="post-access-policies-accesspolicyid-import"></a>Import Access Policy

Starts an import job for this resource

POST /access/policies/{accessPolicyId}/import

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| groupId | false | string | The Group ID to be assigned to the exported archive |
| artifactId | false | string | The Artifact ID to be assigned to the exported archive |
| versionId | false | string | The Version ID to be assigned to the exported archive |
| vaultId | false | string | The ID of the vault where the exported archive should be saved |
| schedule | false | string | Whether to run the job immediately or in the background (either 'synchronous' or 'asynchronous') |

#### Response

```json
{
  "type": "object",
  "description": "Import Configuration",
  "properties": {
    "includeACLs": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include ACLs during import."
    },
    "includeTeams": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Teams during import."
    },
    "includeActivities": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Activities during import."
    },
    "includeBinaries": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Binaries for data stores during import."
    },
    "includeAttachments": {
      "type": "boolean",
      "default": true,
      "description": "Whether to include Attachments for Attachables during import."
    },
    "strategy": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": "CLONE",
      "description": "Either CLONE or COPY_EVERYTHING. Use CLONE to keep the same IDs on import. Use COPY_EVERYTHING to generate all new IDs for all entries on every import."
    },
    "substitutions": {
      "type": "string"
    }
  }
}
```

### <a id="get-access-policies-templates"></a>List Access Policy Templates

Lists access policy templates

GET /access/policies/templates

#### Parameters

This function has no parameters.

### <a id="get-access-policies-system"></a>List System Access Policies

Lists the system access policies

GET /access/policies/system

#### Parameters

This function has no parameters.

### <a id="get-access-policies"></a>Lists Access Policy

Retrieves a list of Access Policy instances

GET /access/policies

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| sort | false | object | Defines how to sort fields in the result set |
| skip | false | number | Skips the result set cursor ahead the specified number of records |
| limit | false | number | Specifies the number of records to be handed back in the result set |

This method supports pagination.

#### Response

```json
{
  "type": "object",
  "description": "Result Map",
  "properties": {
    "total_rows": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "size": {
      "type": "number"
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/resultmap_accessPolicy"
      }
    }
  }
}
```

### <a id="post-access-policies-query"></a>Queries for Access Policy

Queries for instances of type Access Policy

POST /access/policies/query

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| sort | false | object | Defines how to sort fields in the result set |
| skip | false | number | Skips the result set cursor ahead the specified number of records |
| limit | false | number | Specifies the number of records to be handed back in the result set |

This method supports pagination.

#### Response

```json
{
  "type": "object",
  "description": "Result Map",
  "properties": {
    "total_rows": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "size": {
      "type": "number"
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/resultmap_accessPolicy"
      }
    }
  }
}
```

### <a id="get-access-policies-accesspolicyid-acl-list"></a>Read ACL

Read the Access Control List for the specified accessPolicy

GET /access/policies/{accessPolicyId}/acl/list

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |

#### Response

```json
{
  "type": "object",
  "description": "Result Map of ACL entries",
  "properties": {
    "total_rows": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "size": {
      "type": "number"
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "_doc": {
            "type": "string",
            "title": "Principal ID"
          },
          "name": {
            "type": "string",
            "title": "Principal Name"
          },
          "type": {
            "type": "string",
            "title": "Principal Type"
          },
          "domainId": {
            "type": "string"
          },
          "domainQualifiedId": {
            "type": "string"
          },
          "domainQualifiedName": {
            "type": "string"
          },
          "principalId": {
            "type": "string",
            "title": "Principal ID"
          },
          "userEmail": {
            "type": "string"
          },
          "userFirstName": {
            "type": "string"
          },
          "userLastName": {
            "type": "string"
          },
          "authorities": {
            "type": "array",
            "title": "Authorities",
            "items": {
              "type": "string",
              "title": "Authority Key"
            }
          }
        }
      }
    }
  }
}
```

### <a id="get-access-policies-accesspolicyid-acl"></a>Read ACL for Principal

Read the Access Control List for the specified accessPolicy and the given principal

GET /access/policies/{accessPolicyId}/acl

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| id | true | string |  |

#### Response

```json
{
  "type": "object",
  "description": "Result Map of Authority Keys",
  "properties": {
    "total_rows": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "size": {
      "type": "number"
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Authority Key"
      }
    }
  }
}
```

### <a id="get-access-policies-accesspolicyid"></a>Read Access Policy

Reads an instance of a Access Policy

GET /access/policies/{accessPolicyId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |

#### Response

```json
{
  "type": "object",
  "extends": "document",
  "description": "Access Policy",
  "container": "platform",
  "properties": {
    "scope": {
      "type": "string"
    },
    "statements": {
      "type": "array",
      "items": {
        "type": "object",
        "items": {
          "action": {
            "type": "string"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "config": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "order": {
      "type": "string"
    },
    "_doc": null,
    "_system": null
  }
}
```

### <a id="get-access-policies-templates-templatekey"></a>Read Access Policy Template

Read an access policy template

GET /access/policies/templates/{templateKey}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| templateKey | true | string |  |

### <a id="post-access-policies-accesspolicyid-authorities"></a>Read Authorities Report

Read the Authorities Report for the specified accessPolicy

POST /access/policies/{accessPolicyId}/authorities

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |

#### Response

```json
{
  "type": "object",
  "description": "Authority Report",
  "properties": {
    "principalId": {
      "type": "object",
      "properties": {
        "id": {
          "type": "object",
          "properties": {
            "role-key": {
              "type": "string"
            },
            "principal": {
              "type": "string"
            },
            "permissioned": {
              "type": "string"
            },
            "inheritsFrom": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "principal": {
                  "type": "string"
                },
                "permissioned": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

### <a id="get-access-policies-system-key"></a>Read System Access Policy

Read a system access policy

GET /access/policies/system/{key}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| key | true | string |  |

### <a id="post-access-policies-accesspolicyid-authorities-authorityid-revoke"></a>Revoke Authority

Revokes an authority against the specified accessPolicy from a given user

POST /access/policies/{accessPolicyId}/authorities/{authorityId}/revoke

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| authorityId | true | string | The ID or authority key for the authority |
| id | true | string |  |

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indicates whether the operation succeeded or not"
    }
  }
}
```

### <a id="post-access-policies-accesspolicyid-unassign"></a>Unassign Policy

POST /access/policies/{accessPolicyId}/unassign

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |
| ref | true | string |  |

### <a id="post-access-policies-unassignall"></a>Unassignall Policies

POST /access/policies/unassignall

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| ref | true | string |  |

### <a id="put-access-policies-accesspolicyid"></a>Update Access Policy

Updates an existing Access Policy

PUT /access/policies/{accessPolicyId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indicates whether the operation succeeded or not"
    }
  }
}
```

### <a id="post-access-policies-accesspolicyid-update"></a>Update Access Policy

Updates an existing Access Policy

POST /access/policies/{accessPolicyId}/update

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| accessPolicyId | true | string | the ID of the access policy |

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indicates whether the operation succeeded or not"
    }
  }
}
```

## <a id="schema"></a>Schema

```json

{
  "type": "object",
  "extends": "document",
  "description": "Access Policy",
  "container": "platform",
  "properties": {
    "scope": {
      "type": "string"
    },
    "statements": {
      "type": "array",
      "items": {
        "type": "object",
        "items": {
          "action": {
            "type": "string"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "config": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "order": {
      "type": "string"
    },
    "_doc": null,
    "_system": null
  },
  "id": "accessPolicy"
}
```