> For the complete documentation index, see [llms.txt](https://docs.truedat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.truedat.io/v8.12/api-integrations/authentication-management/permission-groups.md).
# Permission Groups
## List permission groups
> Returns every permission group known by the authorization service.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permission_groups":{"get":{"description":"Returns every permission group known by the authorization service.\n","operationId":"TdAuthWeb.PermissionGroupController.index","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionGroupListResponse"}}},"description":"Permission groups list"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List permission groups","tags":["Permission Groups"]}}},"components":{"schemas":{"PermissionGroupListResponse":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/PermissionGroup"},"type":"array"}},"required":["data"],"title":"PermissionGroupListResponse","type":"object"},"PermissionGroup":{"additionalProperties":false,"description":"A group of permissions.","properties":{"id":{"description":"Unique permission group identifier.","type":"integer"},"name":{"description":"Unique permission group name.","type":"string"}},"required":["id","name"],"title":"PermissionGroup","type":"object"},"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```
## Create permission group
> Creates a custom permission group.\
> \
> Requires \*\*administrator\*\* access.\
> \
> The group name must start with the configured custom prefix. Names without the prefix are rejected with \`422\`.\
> \
> Group names are unique: sending an existing name returns \`422\` with a \`"taken"\` error on \`name\`.\
> \
> The response includes a \`Location\` header pointing at the newly created group.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permission_groups":{"post":{"description":"Creates a custom permission group.\n\nRequires **administrator** access.\n\nThe group name must start with the configured custom prefix. Names without the prefix are rejected with `422`.\n\nGroup names are unique: sending an existing name returns `422` with a `\"taken\"` error on `name`.\n\nThe response includes a `Location` header pointing at the newly created group.\n","operationId":"TdAuthWeb.PermissionGroupController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionGroupCreateRequest"}}},"description":"Permission group creation payload","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionGroupResponse"}}},"description":"Permission group created"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnprocessableEntityChangesetResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Create permission group","tags":["Permission Groups"]}}},"components":{"schemas":{"PermissionGroupCreateRequest":{"additionalProperties":false,"description":"Payload for creating a permission group.\n\nThe name must start with the configured custom prefix. Names without the prefix are rejected with `422`.\n","properties":{"permission_group":{"additionalProperties":false,"properties":{"name":{"description":"Permission group name. Must start with the configured custom prefix.","type":"string"}},"required":["name"],"type":"object"}},"required":["permission_group"],"title":"PermissionGroupCreateRequest","type":"object"},"PermissionGroupResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/PermissionGroup"}},"required":["data"],"title":"PermissionGroupResponse","type":"object"},"PermissionGroup":{"additionalProperties":false,"description":"A group of permissions.","properties":{"id":{"description":"Unique permission group identifier.","type":"integer"},"name":{"description":"Unique permission group name.","type":"string"}},"required":["id","name"],"title":"PermissionGroup","type":"object"},"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHForbiddenResponse","type":"object"},"AUTHUnprocessableEntityChangesetResponse":{"additionalProperties":false,"description":"Response emitted for Ecto.Changeset validation failures. Keys under `errors` are the invalid field names and values are lists of messages.","properties":{"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"}},"required":["errors"],"title":"AUTHUnprocessableEntityChangesetResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```
## Get permission group
> Returns the specified permission group.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permission_groups/{id}":{"get":{"description":"Returns the specified permission group.\n","operationId":"TdAuthWeb.PermissionGroupController.show","parameters":[{"description":"Permission group ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionGroupResponse"}}},"description":"Permission group detail"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHNotFoundResponse"}}},"description":"Not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get permission group","tags":["Permission Groups"]}}},"components":{"schemas":{"PermissionGroupResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/PermissionGroup"}},"required":["data"],"title":"PermissionGroupResponse","type":"object"},"PermissionGroup":{"additionalProperties":false,"description":"A group of permissions.","properties":{"id":{"description":"Unique permission group identifier.","type":"integer"},"name":{"description":"Unique permission group name.","type":"string"}},"required":["id","name"],"title":"PermissionGroup","type":"object"},"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHNotFoundResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHNotFoundResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```
## Update permission group
> Updates the name of the specified permission group.\
> \
> Requires \*\*administrator\*\* access.\
> \
> The new name must start with the configured custom prefix. Names without the prefix are rejected with \`422\`.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permission_groups/{id}":{"put":{"description":"Updates the name of the specified permission group.\n\nRequires **administrator** access.\n\nThe new name must start with the configured custom prefix. Names without the prefix are rejected with `422`.\n","operationId":"TdAuthWeb.PermissionGroupController.update","parameters":[{"description":"Permission group ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionGroupUpdateRequest"}}},"description":"Permission group update payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionGroupResponse"}}},"description":"Permission group updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHNotFoundResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnprocessableEntityChangesetResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update permission group","tags":["Permission Groups"]}}},"components":{"schemas":{"PermissionGroupUpdateRequest":{"additionalProperties":false,"description":"Payload for updating a permission group.\n\nThe new name must start with the configured custom prefix. Names without the prefix are rejected with `422`.\n","properties":{"permission_group":{"additionalProperties":false,"properties":{"name":{"description":"New permission group name. Must start with the configured custom prefix.","nullable":true,"type":"string"}},"type":"object"}},"required":["permission_group"],"title":"PermissionGroupUpdateRequest","type":"object"},"PermissionGroupResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/PermissionGroup"}},"required":["data"],"title":"PermissionGroupResponse","type":"object"},"PermissionGroup":{"additionalProperties":false,"description":"A group of permissions.","properties":{"id":{"description":"Unique permission group identifier.","type":"integer"},"name":{"description":"Unique permission group name.","type":"string"}},"required":["id","name"],"title":"PermissionGroup","type":"object"},"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHForbiddenResponse","type":"object"},"AUTHNotFoundResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHNotFoundResponse","type":"object"},"AUTHUnprocessableEntityChangesetResponse":{"additionalProperties":false,"description":"Response emitted for Ecto.Changeset validation failures. Keys under `errors` are the invalid field names and values are lists of messages.","properties":{"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"}},"required":["errors"],"title":"AUTHUnprocessableEntityChangesetResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```
## Delete permission group
> Permanently deletes the specified permission group.\
> \
> Requires \*\*administrator\*\* access.\
> \
> A permission group that still has permissions attached cannot be deleted: the request is rejected with \`422\`.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permission_groups/{id}":{"delete":{"description":"Permanently deletes the specified permission group.\n\nRequires **administrator** access.\n\nA permission group that still has permissions attached cannot be deleted: the request is rejected with `422`.\n","operationId":"TdAuthWeb.PermissionGroupController.delete","parameters":[{"description":"Permission group ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Permission group deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHNotFoundResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnprocessableEntityChangesetResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Delete permission group","tags":["Permission Groups"]}}},"components":{"schemas":{"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHForbiddenResponse","type":"object"},"AUTHNotFoundResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHNotFoundResponse","type":"object"},"AUTHUnprocessableEntityChangesetResponse":{"additionalProperties":false,"description":"Response emitted for Ecto.Changeset validation failures. Keys under `errors` are the invalid field names and values are lists of messages.","properties":{"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"}},"required":["errors"],"title":"AUTHUnprocessableEntityChangesetResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```
## Update permission group
> Updates the name of the specified permission group.\
> \
> Requires \*\*administrator\*\* access.\
> \
> The new name must start with the configured custom prefix. Names without the prefix are rejected with \`422\`.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permission_groups/{id}":{"patch":{"description":"Updates the name of the specified permission group.\n\nRequires **administrator** access.\n\nThe new name must start with the configured custom prefix. Names without the prefix are rejected with `422`.\n","operationId":"TdAuthWeb.PermissionGroupController.update (2)","parameters":[{"description":"Permission group ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionGroupUpdateRequest"}}},"description":"Permission group update payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionGroupResponse"}}},"description":"Permission group updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHNotFoundResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnprocessableEntityChangesetResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update permission group","tags":["Permission Groups"]}}},"components":{"schemas":{"PermissionGroupUpdateRequest":{"additionalProperties":false,"description":"Payload for updating a permission group.\n\nThe new name must start with the configured custom prefix. Names without the prefix are rejected with `422`.\n","properties":{"permission_group":{"additionalProperties":false,"properties":{"name":{"description":"New permission group name. Must start with the configured custom prefix.","nullable":true,"type":"string"}},"type":"object"}},"required":["permission_group"],"title":"PermissionGroupUpdateRequest","type":"object"},"PermissionGroupResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/PermissionGroup"}},"required":["data"],"title":"PermissionGroupResponse","type":"object"},"PermissionGroup":{"additionalProperties":false,"description":"A group of permissions.","properties":{"id":{"description":"Unique permission group identifier.","type":"integer"},"name":{"description":"Unique permission group name.","type":"string"}},"required":["id","name"],"title":"PermissionGroup","type":"object"},"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHForbiddenResponse","type":"object"},"AUTHNotFoundResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHNotFoundResponse","type":"object"},"AUTHUnprocessableEntityChangesetResponse":{"additionalProperties":false,"description":"Response emitted for Ecto.Changeset validation failures. Keys under `errors` are the invalid field names and values are lists of messages.","properties":{"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"}},"required":["errors"],"title":"AUTHUnprocessableEntityChangesetResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```