---
title: "Domain Principal"
description: "Discover the capabilities of Domain Principal, an essential object in our API platform with comprehensive method and property details. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/reference/types/principal"
---

# <a id="top"></a>Domain Principal

An Object

1.  [Platform](/documentation/gitana/4.0/reference/types/platform.md)
2.  [Domain](/documentation/gitana/4.0/reference/types/domain.md)
3.  [Domain Principal](/documentation/gitana/4.0/reference/types/principal.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 Domain Principal is contained within a [Domain](/documentation/gitana/4.0/reference/types/domain.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 |
| authorities | array |  | No |  |
| name | string |  | No |  |
| type | string |  | No |  |

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

The following methods are available:

- [Add Member](#post-domains-domainid-principals-principalid-members-add "Add Member")
- [Check Membership](#post-domains-domainid-principals-membership-check "Check Membership")
- [Check Memberships](#post-domains-domainid-principals-memberships-check "Check Memberships")
- [Check Permission](#post-domains-domainid-principals-permissionedid-permissions-permissionid-check "Check Permission")
- [Check Single Authority](#post-domains-domainid-principals-permissionedid-authorities-authorityid-check "Check Single Authority")
- [Check multiple Authorities](#post-domains-domainid-principals-authorities-check "Check multiple Authorities")
- [Check multiple Permissions](#post-domains-domainid-principals-permissions-check "Check multiple Permissions")
- [Create Domain Principal](#post-domains-domainid-principals "Create Domain Principal")
- [Delete Attachment](#delete-domains-domainid-principals-principalid-attachments-attachmentid "Delete Attachment")
- [Delete Domain Principal](#delete-domains-domainid-principals-principalid "Delete Domain Principal")
- [Download Attachment](#get-domains-domainid-principals-principalid-attachments-attachmentid "Download Attachment")
- [Download Preview](#get-domains-domainid-principals-principalid-preview-name "Download Preview")
- [Export Domain Principal](#post-domains-domainid-principals-principalid-export "Export Domain Principal")
- [Grant Authority](#post-domains-domainid-principals-permissionedid-authorities-authorityid-grant "Grant Authority")
- [Import Domain Principal](#post-domains-domainid-principals-principalid-import "Import Domain Principal")
- [Invite User](#post-domains-domainid-principals-invite "Invite User")
- [List Attachments](#get-domains-domainid-principals-principalid-attachments "List Attachments")
- [List Members](#get-domains-domainid-principals-principalid-members "List Members")
- [List Memberships](#get-domains-domainid-principals-principalid-memberships "List Memberships")
- [List Teams](#get-domains-domainid-principals-principalid-teams "List Teams")
- [Lists Domain Principal](#get-domains-domainid-principals "Lists Domain Principal")
- [Query](#post-domains-domainid-principals-query "Query")
- [Read ACL](#get-domains-domainid-principals-permissionedid-acl-list "Read ACL")
- [Read ACL for Principal](#get-domains-domainid-principals-permissionedid-acl "Read ACL for Principal")
- [Read Authorities Report](#post-domains-domainid-principals-permissionedid-authorities "Read Authorities Report")
- [Read Domain Principal](#get-domains-domainid-principals-principalid "Read Domain Principal")
- [Remove Member](#post-domains-domainid-principals-principalid-members-remove "Remove Member")
- [Revoke Authority](#post-domains-domainid-principals-permissionedid-authorities-authorityid-revoke "Revoke Authority")
- [Summarize Access Policy](#get-domains-domainid-principals-principalid-access-policies-summary "Summarize Access Policy")
- [Update Domain Principal](#put-domains-domainid-principals-principalid "Update Domain Principal")
- [Upload Attachment](#post-domains-domainid-principals-principalid-attachments-attachmentid "Upload Attachment")
- [Upload Attachments](#post-domains-domainid-principals-principalid-attachments "Upload Attachments")

### <a id="post-domains-domainid-principals-principalid-members-add"></a>Add Member

Adds a principal to a group

POST /domains/{domainId}/principals/{principalId}/members/add

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| 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-domains-domainid-principals-membership-check"></a>Check Membership

POST /domains/{domainId}/principals/membership/check

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |

### <a id="post-domains-domainid-principals-memberships-check"></a>Check Memberships

POST /domains/{domainId}/principals/memberships/check

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |

### <a id="post-domains-domainid-principals-permissionedid-permissions-permissionid-check"></a>Check Permission

Checks whether an actor has a permission over a principal

POST /domains/{domainId}/principals/{permissionedId}/permissions/{permissionId}/check

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| permissionedId | true | string | The ID of the permissioned object or datastore |
| permissionId | true | string | The ID of the permission |
| id | true | string |  |

#### Response

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

### <a id="post-domains-domainid-principals-permissionedid-authorities-authorityid-check"></a>Check Single Authority

Checks whether an actor has an authority over a principal

POST /domains/{domainId}/principals/{permissionedId}/authorities/{authorityId}/check

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| permissionedId | true | string | The ID of the permissioned object or datastore |
| 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-domains-domainid-principals-authorities-check"></a>Check multiple Authorities

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

POST /domains/{domainId}/principals/authorities/check

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |

#### 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-domains-domainid-principals-permissions-check"></a>Check multiple Permissions

Checks whether multiple actors have permissions over a principal

POST /domains/{domainId}/principals/permissions/check

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| HTTP Payload | true | string | HTTP Payload |

#### Response

```json
{
  "type": "object",
  "description": "List of results for Principals that were Checked",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "permissionedId": {
            "type": "string"
          },
          "principalId": {
            "type": "string"
          },
          "permissionId": {
            "type": "string"
          },
          "result": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

### <a id="post-domains-domainid-principals"></a>Create Domain Principal

Creates a new Domain Principal

POST /domains/{domainId}/principals

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | , The incoming JSON payload should contain properties for the newly created principal. If a 'password' property is provided, an identity will be created in the domain's default directory. , |

The incoming JSON payload should contain properties for the newly created principal. If a 'password' property is provided, an identity will be created in the domain's default directory.

#### Response

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

### <a id="delete-domains-domainid-principals-principalid-attachments-attachmentid"></a>Delete Attachment

Deletes an attachment

DELETE /domains/{domainId}/principals/{principalId}/attachments/{attachmentId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| attachmentId | true | string |  |

#### Response

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

### <a id="delete-domains-domainid-principals-principalid"></a>Delete Domain Principal

Deletes an existing Domain Principal

DELETE /domains/{domainId}/principals/{principalId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |

#### Response

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

### <a id="get-domains-domainid-principals-principalid-attachments-attachmentid"></a>Download Attachment

Downloads an attachment

GET /domains/{domainId}/principals/{principalId}/attachments/{attachmentId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| attachmentId | true | string |  |
| a | false | string | If true, the 'Content-Disposition' header will be set |

### <a id="get-domains-domainid-principals-principalid-preview-name"></a>Download Preview

Downloads a preview stream of a principal attachment

GET /domains/{domainId}/principals/{principalId}/preview/{name}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| name | true | string |  |
| mimetype | false | string | The mimetype to be streamed back (defaults to 'image/png') |
| size | false | number | For image mimetypes, the max width of the generated image (defaults to 64) |
| attachment | false | string | The ID of the attachment that serves as the source for the preview (default to 'default') |
| force | false | boolean | Forces the re-generation of the preview stream, even if previously saved |
| save | false | boolean | Specifies whether to save the generated preview stream as an attachment (defaults to true) |
| fallback | false | boolean | A fallback URL that should be redirected to in the event that a preview stream cannot be generated |

### <a id="post-domains-domainid-principals-principalid-export"></a>Export Domain Principal

Starts an export job for this resource

POST /domains/{domainId}/principals/{principalId}/export

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| 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-domains-domainid-principals-permissionedid-authorities-authorityid-grant"></a>Grant Authority

Grants an authority over a principal to an actor

POST /domains/{domainId}/principals/{permissionedId}/authorities/{authorityId}/grant

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| permissionedId | true | string | The ID of the permissioned object or datastore |
| 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-domains-domainid-principals-principalid-import"></a>Import Domain Principal

Starts an import job for this resource

POST /domains/{domainId}/principals/{principalId}/import

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| 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="post-domains-domainid-principals-invite"></a>Invite User

Invites a user to a domain

POST /domains/{domainId}/principals/invite

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| id | true | string |  |

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation (with ID)",
  "extends": "status",
  "properties": {
    "_doc": {
      "type": "string"
    },
    "ok": null
  }
}
```

### <a id="get-domains-domainid-principals-principalid-attachments"></a>List Attachments

Lists the attachments for a principal

GET /domains/{domainId}/principals/{principalId}/attachments

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |

#### 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_attachment"
      }
    }
  }
}
```

### <a id="get-domains-domainid-principals-principalid-members"></a>List Members

Lists the principals belonging to a group

GET /domains/{domainId}/principals/{principalId}/members

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| 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_domainprincipal"
      }
    }
  }
}
```

### <a id="get-domains-domainid-principals-principalid-memberships"></a>List Memberships

Lists the groups that a principal belongs to

GET /domains/{domainId}/principals/{principalId}/memberships

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| 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_domainprincipal"
      }
    }
  }
}
```

### <a id="get-domains-domainid-principals-principalid-teams"></a>List Teams

Lists the teams that a principal belongs to against a given teamable

GET /domains/{domainId}/principals/{principalId}/teams

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| teamableType | true | string |  |
| teamableId | true | string |  |
| 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_domainprincipal"
      }
    }
  }
}
```

### <a id="get-domains-domainid-principals"></a>Lists Domain Principal

Retrieves a list of Domain Principal instances

GET /domains/{domainId}/principals

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| groups | false | string |  |
| 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_domainprincipal"
      }
    }
  }
}
```

### <a id="post-domains-domainid-principals-query"></a>Query

Queries for matches

POST /domains/{domainId}/principals/query

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| groups | false | string |  |
| 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_domainprincipal"
      }
    }
  }
}
```

### <a id="get-domains-domainid-principals-permissionedid-acl-list"></a>Read ACL

Read the Access Control List for the specified principal

GET /domains/{domainId}/principals/{permissionedId}/acl/list

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| permissionedId | true | string | The ID of the permissioned object or datastore |

#### 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-domains-domainid-principals-permissionedid-acl"></a>Read ACL for Principal

Reads the ACL for a principal and specific actor

GET /domains/{domainId}/principals/{permissionedId}/acl

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| permissionedId | true | string | The ID of the permissioned object or datastore |
| 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="post-domains-domainid-principals-permissionedid-authorities"></a>Read Authorities Report

Generates an authority report for a set of principals

POST /domains/{domainId}/principals/{permissionedId}/authorities

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| permissionedId | true | string | The ID of the permissioned object or datastore |
| HTTP Payload | true | string | HTTP Payload |

#### Response

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

### <a id="get-domains-domainid-principals-principalid"></a>Read Domain Principal

Reads an instance of a Domain Principal

GET /domains/{domainId}/principals/{principalId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| groups | false | string |  |

#### Response

```json
{
  "type": "object",
  "extends": "document",
  "description": "Domain Principal",
  "container": "domain",
  "properties": {
    "name": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "authorities": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Authority Key"
      }
    },
    "_doc": null,
    "_system": null
  }
}
```

### <a id="post-domains-domainid-principals-principalid-members-remove"></a>Remove Member

Removes a principal from a group

POST /domains/{domainId}/principals/{principalId}/members/remove

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| 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-domains-domainid-principals-permissionedid-authorities-authorityid-revoke"></a>Revoke Authority

Revokes an authority over a principal from an actor

POST /domains/{domainId}/principals/{permissionedId}/authorities/{authorityId}/revoke

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| permissionedId | true | string | The ID of the permissioned object or datastore |
| 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="get-domains-domainid-principals-principalid-access-policies-summary"></a>Summarize Access Policy

Retrieves an access policy summary for a user

GET /domains/{domainId}/principals/{principalId}/access/policies/summary

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| scope | false | string |  |
| info | false | string |  |

#### 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="put-domains-domainid-principals-principalid"></a>Update Domain Principal

Updates an existing Domain Principal

PUT /domains/{domainId}/principals/{principalId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | , The incoming JSON payload should contain the full set of properties to be updated onto the principal. A special 'password' property can be supplied to change a domain user's password. , |

The incoming JSON payload should contain the full set of properties to be updated onto the principal. A special 'password' property can be supplied to change a domain user's password.

#### Response

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

### <a id="post-domains-domainid-principals-principalid-attachments-attachmentid"></a>Upload Attachment

Uploads an attachment

POST /domains/{domainId}/principals/{principalId}/attachments/{attachmentId}

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |
| attachmentId | true | string |  |

Supports both URLEncoded and MultiPart requests

#### Response

```json
{
  "type": "object",
  "description": "Status of Operation (with ID)",
  "extends": "status",
  "properties": {
    "_doc": {
      "type": "string"
    },
    "ok": null
  }
}
```

### <a id="post-domains-domainid-principals-principalid-attachments"></a>Upload Attachments

Uploads one or more attachments

POST /domains/{domainId}/principals/{principalId}/attachments

#### Parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| domainId | true | string | The ID of the domain |
| principalId | true | string | The ID of the principal |

Only supports MultiPart requests

#### 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_attachment"
      }
    }
  }
}
```

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

```json

{
  "type": "object",
  "extends": "document",
  "description": "Domain Principal",
  "container": "domain",
  "properties": {
    "name": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "authorities": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Authority Key"
      }
    },
    "_doc": null,
    "_system": null
  },
  "id": "principal"
}
```