# Access management Use the API to retrieve information about users and groups, and to manage access to datasets. ## List users > Returns all users in your organization. Users with 'Manage Users and Groups' permission receive additional account metadata.\ > \### Required Permissions\ > \ > \- \*\*Global:\*\* View Users And Groups
```json {"openapi":"3.0.4","info":{"title":"Textual API","version":"vDev"},"tags":[{"name":"Users","description":"Retrieve users within your organization."}],"security":[{}],"paths":{"/api/Users":{"get":{"tags":["Users"],"summary":"List users","description":"Returns all users in your organization. Users with 'Manage Users and Groups' permission receive additional account metadata.\n### Required Permissions\n\n- **Global:** View Users And Groups\n","responses":{"200":{"description":"Returns organization users","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EnrichedUserEntityModel"}}}}}}}}},"components":{"schemas":{"EnrichedUserEntityModel":{"required":["id","userName"],"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the user or group."},"userName":{"type":"string","description":"The display name of the user or group.","nullable":true},"firstName":{"type":"string","description":"The user's first name.","nullable":true},"lastName":{"type":"string","description":"The user's last name.","nullable":true},"organizationId":{"type":"string","description":"The identifier of the organization the user belongs to.","nullable":true},"photoMetadata":{"allOf":[{"$ref":"#/components/schemas/UserPhotoModel"}],"description":"Metadata about the user's profile photo, if available.","nullable":true},"accountMetadata":{"allOf":[{"$ref":"#/components/schemas/UserEntityMetadata"}],"description":"Additional account metadata such as creation date and last activity. Populated only for callers with sufficient privileges.","nullable":true},"teamName":{"type":"string","description":"The name of the team the user belongs to, if set.","nullable":true}},"additionalProperties":false,"description":"A user entity with extended profile information including organization, photo, and account metadata."},"UserPhotoModel":{"required":["name"],"type":"object","properties":{"name":{"type":"string","description":"The file name of the photo."},"url":{"type":"string","description":"The URL where the photo can be accessed, if available.","nullable":true},"fileType":{"type":"string","description":"The MIME type of the photo (e.g. image/png).","nullable":true},"content":{"type":"string","description":"The raw byte content of the photo, if loaded.","format":"byte","nullable":true},"isManualUpload":{"type":"boolean","description":"Whether the photo was manually uploaded by the user (as opposed to sourced from SSO)."}},"additionalProperties":false,"description":"Metadata about a user's profile photo."},"UserEntityMetadata":{"type":"object","properties":{"createdAt":{"allOf":[{"$ref":"#/components/schemas/Instant"}],"description":"The date and time when the user account was created."},"lastActivityDate":{"allOf":[{"$ref":"#/components/schemas/Instant"}],"description":"The date and time of the user's most recent activity, if any.","nullable":true}},"additionalProperties":false,"description":"Account-level metadata for a user, including creation and activity timestamps."},"Instant":{"type":"object","additionalProperties":false,"description":"A point in time represented as an ISO 8601 timestamp string."}}}} ``` ## List groups > Returns all groups in your organization. Returns an empty list in hosted environments.\ > \### Required Permissions\ > \ > \- \*\*Global:\*\* View Users And Groups
```json {"openapi":"3.0.4","info":{"title":"Textual API","version":"vDev"},"tags":[{"name":"Groups","description":"Retrieve groups within your organization."}],"security":[{}],"paths":{"/api/Groups":{"get":{"tags":["Groups"],"summary":"List groups","description":"Returns all groups in your organization. Returns an empty list in hosted environments.\n### Required Permissions\n\n- **Global:** View Users And Groups\n","responses":{"200":{"description":"Returns the list of groups","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GroupEntityModel"}}}}}}}}},"components":{"schemas":{"GroupEntityModel":{"required":["context","id","userName"],"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the user or group."},"userName":{"type":"string","description":"The display name of the user or group.","nullable":true},"context":{"enum":["None","Google","Okta","Azure","OIDC","Keycloak"],"allOf":[{"$ref":"#/components/schemas/GroupContext"}],"description":"Enum representing the unique context that a Solar.EF.Models.Group belongs to. For example, Organizations may use multiple SSO providers for\nauthentication, and Groups are only unique by name within a particular context."}},"additionalProperties":false,"description":"A group entity that can be assigned permissions on resources."},"GroupContext":{"enum":["None","Google","Okta","Azure","OIDC","Keycloak"],"type":"string","description":"Enum representing the unique context that a Solar.EF.Models.Group belongs to. For example, Organizations may use multiple SSO providers for\nauthentication, and Groups are only unique by name within a particular context."}}}} ``` ## List permission sets > Users that have the global permission Manage Permission Sets get the full details, including the available operations.\ > \### Required Permissions\ > \ > \- \*\*Global (At least 1 of the following):\*\* Manage Permission Sets, Manage User Global Permissions
```json {"openapi":"3.0.4","info":{"title":"Textual API","version":"vDev"},"tags":[{"name":"Permission Sets","description":"Retrieve permission sets that define named collections of operations grantable to users and groups."}],"security":[{}],"paths":{"/api/permission-sets":{"get":{"tags":["Permission Sets"],"summary":"List permission sets","description":"Users that have the global permission Manage Permission Sets get the full details, including the available operations.\n### Required Permissions\n\n- **Global (At least 1 of the following):** Manage Permission Sets, Manage User Global Permissions\n","parameters":[{"name":"type","in":"query","description":"Optional filter for the types of permission sets to retrieve","schema":{"type":"array","items":{"$ref":"#/components/schemas/PermissionSetType"}}}],"responses":{"200":{"description":"Returns the list of permission sets","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PermissionSetModel"}}}}},"400":{"description":"Invalid filter parameters","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"PermissionSetType":{"enum":["Global","Dataset","CustomEntity","ManualRedactionProject"],"type":"string","description":"The type discriminator for Permission Sets which determines the kinds of operations available to that Permission Set.

Possible values:

\n\n"},"PermissionSetModel":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The ID of the permission set."},"type":{"enum":["Global","Dataset","CustomEntity","ManualRedactionProject"],"allOf":[{"$ref":"#/components/schemas/PermissionSetType"}],"description":"The type discriminator for Permission Sets which determines the kinds of operations available to that Permission Set.

Possible values:

\n\n"},"name":{"type":"string","description":"The name of the permission set."},"isBuiltIn":{"type":"boolean","description":"Whether the permission set is built-in."},"isDefault":{"type":"boolean","description":"Whether the permission set is the default permission set for its type."},"isDisabled":{"type":"boolean","description":"Whether the permission set is disabled."},"lastModifiedDate":{"allOf":[{"$ref":"#/components/schemas/Instant"}],"description":"The date when the permission set was last modified."},"operations":{"type":"array","items":{"type":"integer","format":"int32"},"description":"The operations of the permission set. Only included for users with `Manage Permission Sets` permission.","nullable":true},"createdDate":{"allOf":[{"$ref":"#/components/schemas/Instant"}],"description":"The date when the permission set was created. Only included for users with `Manage Permission Sets` permission.","nullable":true},"lastModifiedByUserId":{"type":"string","description":"The ID of the user who last modified the permission set. Only included for users with `Manage Permission Sets` permission.","nullable":true}},"additionalProperties":false,"description":"A permission set that defines a named collection of operations that can be granted to users or groups."},"Instant":{"type":"object","additionalProperties":false,"description":"A point in time represented as an ISO 8601 timestamp string."},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{},"description":"Standard error response following RFC 7807, containing error type, title, status code, and detail message."}}}} ``` ## List dataset shares > Returns all user and group permission assignments for the specified dataset. ```json {"openapi":"3.0.4","info":{"title":"Textual API","version":"vDev"},"tags":[{"name":"Dataset Management","description":"Manage datasets for PII detection and redaction. Create, search, and edit datasets, upload and download files, and control dataset sharing permissions."}],"security":[{}],"paths":{"/api/dataset/{datasetId}/shares":{"get":{"tags":["Dataset Management"],"summary":"List dataset shares","description":"Returns all user and group permission assignments for the specified dataset.","parameters":[{"name":"datasetId","in":"path","description":"The unique identifier of the dataset","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns dataset permission assignments","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ResourcePermissionSetAssignmentModel"}}}}},"404":{"description":"Dataset not found","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"ResourcePermissionSetAssignmentModel":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the share."},"permissionSetId":{"type":"string","description":"The ID of the permission set that is shared."},"sharedWithUser":{"allOf":[{"$ref":"#/components/schemas/UserEntityModel"}],"description":"The user that the dataset is shared with. If the dataset is shared with a group, then this field is null.","nullable":true},"sharedWithGroup":{"allOf":[{"$ref":"#/components/schemas/GroupEntityModel"}],"description":"The group that the dataset is shared with. If the dataset is shared with a user, then this field is null.","nullable":true},"shareableEntityType":{"enum":["User","Group"],"allOf":[{"$ref":"#/components/schemas/ShareableEntityTypeEnum"}],"description":"Indicates whether the dataset was shared with a user or with a group.

Possible values:

\n\n"},"resourceId":{"type":"string","description":"The ID of the dataset that is shared."}},"additionalProperties":false,"description":"A model that represents a user or a group that was assigned a permission set for a dataset."},"UserEntityModel":{"required":["id","userName"],"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the user or group."},"userName":{"type":"string","description":"The display name of the user or group.","nullable":true},"firstName":{"type":"string","description":"The user's first name.","nullable":true},"lastName":{"type":"string","description":"The user's last name.","nullable":true}},"additionalProperties":false,"description":"A user entity with basic identity information."},"GroupEntityModel":{"required":["context","id","userName"],"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the user or group."},"userName":{"type":"string","description":"The display name of the user or group.","nullable":true},"context":{"enum":["None","Google","Okta","Azure","OIDC","Keycloak"],"allOf":[{"$ref":"#/components/schemas/GroupContext"}],"description":"Enum representing the unique context that a Solar.EF.Models.Group belongs to. For example, Organizations may use multiple SSO providers for\nauthentication, and Groups are only unique by name within a particular context."}},"additionalProperties":false,"description":"A group entity that can be assigned permissions on resources."},"GroupContext":{"enum":["None","Google","Okta","Azure","OIDC","Keycloak"],"type":"string","description":"Enum representing the unique context that a Solar.EF.Models.Group belongs to. For example, Organizations may use multiple SSO providers for\nauthentication, and Groups are only unique by name within a particular context."},"ShareableEntityTypeEnum":{"enum":["User","Group"],"type":"string","description":"

Possible values:

\n\n"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{},"description":"Standard error response following RFC 7807, containing error type, title, status code, and detail message."}}}} ``` ## Modify dataset shares > Adds or removes user and group permission assignments for the specified dataset in bulk. ```json {"openapi":"3.0.4","info":{"title":"Textual API","version":"vDev"},"tags":[{"name":"Dataset Management","description":"Manage datasets for PII detection and redaction. Create, search, and edit datasets, upload and download files, and control dataset sharing permissions."}],"security":[{}],"paths":{"/api/dataset/{datasetId}/shares/bulk":{"post":{"tags":["Dataset Management"],"summary":"Modify dataset shares","description":"Adds or removes user and group permission assignments for the specified dataset in bulk.","parameters":[{"name":"datasetId","in":"path","description":"The ID of the dataset","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Request that contains the users or groups to grant permissions to or revoke permissions from on the dataset.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ModifyResourcePermissionSetAssignmentsRequestModel"}],"description":"A request to modify the permission assignments for a dataset."}}}},"responses":{"200":{"description":"Returns modified permission assignments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModifyResourcePermissionSetAssignmentsModel"}}}},"400":{"description":"Invalid request body or model validation failed","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}},"404":{"description":"Dataset not found","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"ModifyResourcePermissionSetAssignmentsRequestModel":{"type":"object","properties":{"grant":{"type":"array","items":{"$ref":"#/components/schemas/ResourcePermissionAssignmentRequestModel"},"description":"The permission sets to grant access to."},"revoke":{"type":"array","items":{"$ref":"#/components/schemas/ResourcePermissionAssignmentRequestModel"},"description":"The permission sets to remove access from."}},"additionalProperties":false,"description":"A request to modify the permission assignments for a dataset."},"ResourcePermissionAssignmentRequestModel":{"required":["permissionSetId"],"type":"object","properties":{"sharedWithUserId":{"type":"string","description":"The user that is shared a permission set. This field should be left null if sharing with a group.","nullable":true},"sharedWithGroupId":{"type":"string","description":"The group that is shared a permission set. This field should be left null if sharing with a user.","nullable":true},"permissionSetId":{"type":"string","description":"The ID of the permission set to assign."}},"additionalProperties":false,"description":"References the user or group and the set of permissions to modify on a dataset."},"ModifyResourcePermissionSetAssignmentsModel":{"type":"object","properties":{"granted":{"type":"array","items":{"$ref":"#/components/schemas/ResourcePermissionSetAssignmentModel"},"description":"The permission set assignments that were granted."},"revoked":{"type":"array","items":{"$ref":"#/components/schemas/ResourcePermissionSetAssignmentModel"},"description":"The permission set assignments that were revoked."}},"additionalProperties":false,"description":"Response for modifying the permission set assignments of a dataset."},"ResourcePermissionSetAssignmentModel":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the share."},"permissionSetId":{"type":"string","description":"The ID of the permission set that is shared."},"sharedWithUser":{"allOf":[{"$ref":"#/components/schemas/UserEntityModel"}],"description":"The user that the dataset is shared with. If the dataset is shared with a group, then this field is null.","nullable":true},"sharedWithGroup":{"allOf":[{"$ref":"#/components/schemas/GroupEntityModel"}],"description":"The group that the dataset is shared with. If the dataset is shared with a user, then this field is null.","nullable":true},"shareableEntityType":{"enum":["User","Group"],"allOf":[{"$ref":"#/components/schemas/ShareableEntityTypeEnum"}],"description":"Indicates whether the dataset was shared with a user or with a group.

Possible values:

\n\n"},"resourceId":{"type":"string","description":"The ID of the dataset that is shared."}},"additionalProperties":false,"description":"A model that represents a user or a group that was assigned a permission set for a dataset."},"UserEntityModel":{"required":["id","userName"],"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the user or group."},"userName":{"type":"string","description":"The display name of the user or group.","nullable":true},"firstName":{"type":"string","description":"The user's first name.","nullable":true},"lastName":{"type":"string","description":"The user's last name.","nullable":true}},"additionalProperties":false,"description":"A user entity with basic identity information."},"GroupEntityModel":{"required":["context","id","userName"],"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the user or group."},"userName":{"type":"string","description":"The display name of the user or group.","nullable":true},"context":{"enum":["None","Google","Okta","Azure","OIDC","Keycloak"],"allOf":[{"$ref":"#/components/schemas/GroupContext"}],"description":"Enum representing the unique context that a Solar.EF.Models.Group belongs to. For example, Organizations may use multiple SSO providers for\nauthentication, and Groups are only unique by name within a particular context."}},"additionalProperties":false,"description":"A group entity that can be assigned permissions on resources."},"GroupContext":{"enum":["None","Google","Okta","Azure","OIDC","Keycloak"],"type":"string","description":"Enum representing the unique context that a Solar.EF.Models.Group belongs to. For example, Organizations may use multiple SSO providers for\nauthentication, and Groups are only unique by name within a particular context."},"ShareableEntityTypeEnum":{"enum":["User","Group"],"type":"string","description":"

Possible values:

\n\n"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{},"description":"Standard error response following RFC 7807, containing error type, title, status code, and detail message."}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tonic.ai/textual/textual-rest-api/access-management.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.