> 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/permissions.md).
# Permissions
## List permissions
> Returns every permission known by the authorization service, including the permission group it belongs to.\
> \
> Requires an account with administrative privileges (\*\*administrator or service account\*\*).
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permissions":{"get":{"description":"Returns every permission known by the authorization service, including the permission group it belongs to.\n\nRequires an account with administrative privileges (**administrator or service account**).\n","operationId":"TdAuthWeb.PermissionController.index","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionListResponse"}}},"description":"Permissions list"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List permissions","tags":["Permissions"]}}},"components":{"schemas":{"PermissionListResponse":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Permission"},"type":"array"}},"required":["data"],"title":"PermissionListResponse","type":"object"},"Permission":{"additionalProperties":false,"description":"A permission known by the authorization service.\n\nThe `group` field is present when the permission group has been preloaded. It is absent on responses produced immediately after a creation, where the association has not been loaded yet.\n","properties":{"group":{"$ref":"#/components/schemas/PermissionGroupRef"},"id":{"description":"Unique permission identifier.","type":"integer"},"name":{"description":"Unique permission name.","type":"string"}},"required":["id","name"],"title":"Permission","type":"object"},"PermissionGroupRef":{"additionalProperties":false,"description":"Permission group embedded inside a permission.","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"title":"PermissionGroupRef","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"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```
## Create permission
> Creates a custom permission.\
> \
> Requires \*\*administrator\*\* access.\
> \
> The permission name must start with the configured custom prefix. Names without the prefix are rejected with \`422\`.\
> \
> Permission 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 permission.\
> \
> The \`group\` field is \*\*not\*\* present in the \`201\` response, because the association is not preloaded after the insert. It is present on subsequent \`show\` or \`index\` responses.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permissions":{"post":{"description":"Creates a custom permission.\n\nRequires **administrator** access.\n\nThe permission name must start with the configured custom prefix. Names without the prefix are rejected with `422`.\n\nPermission 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 permission.\n\nThe `group` field is **not** present in the `201` response, because the association is not preloaded after the insert. It is present on subsequent `show` or `index` responses.\n","operationId":"TdAuthWeb.PermissionController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionCreateRequest"}}},"description":"Permission creation payload","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionResponse"}}},"description":"Permission 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","tags":["Permissions"]}}},"components":{"schemas":{"PermissionCreateRequest":{"additionalProperties":false,"description":"Payload for creating a permission.\n\nThe name must start with the configured custom prefix. Names without the prefix are rejected with `422`, even if the rest of the payload is valid.\n","properties":{"permission":{"additionalProperties":false,"properties":{"name":{"description":"Permission name. Must start with the configured custom prefix.","type":"string"},"permission_group_id":{"description":"Identifier of the permission group the permission belongs to.","type":"integer"}},"required":["name"],"type":"object"}},"required":["permission"],"title":"PermissionCreateRequest","type":"object"},"PermissionResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Permission"}},"required":["data"],"title":"PermissionResponse","type":"object"},"Permission":{"additionalProperties":false,"description":"A permission known by the authorization service.\n\nThe `group` field is present when the permission group has been preloaded. It is absent on responses produced immediately after a creation, where the association has not been loaded yet.\n","properties":{"group":{"$ref":"#/components/schemas/PermissionGroupRef"},"id":{"description":"Unique permission identifier.","type":"integer"},"name":{"description":"Unique permission name.","type":"string"}},"required":["id","name"],"title":"Permission","type":"object"},"PermissionGroupRef":{"additionalProperties":false,"description":"Permission group embedded inside a permission.","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"title":"PermissionGroupRef","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
> Returns the specified permission together with its permission group.\
> \
> Requires an account with administrative privileges (\*\*administrator or service account\*\*).
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permissions/{id}":{"get":{"description":"Returns the specified permission together with its permission group.\n\nRequires an account with administrative privileges (**administrator or service account**).\n","operationId":"TdAuthWeb.PermissionController.show","parameters":[{"description":"Permission ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionResponse"}}},"description":"Permission detail"},"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"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get permission","tags":["Permissions"]}}},"components":{"schemas":{"PermissionResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Permission"}},"required":["data"],"title":"PermissionResponse","type":"object"},"Permission":{"additionalProperties":false,"description":"A permission known by the authorization service.\n\nThe `group` field is present when the permission group has been preloaded. It is absent on responses produced immediately after a creation, where the association has not been loaded yet.\n","properties":{"group":{"$ref":"#/components/schemas/PermissionGroupRef"},"id":{"description":"Unique permission identifier.","type":"integer"},"name":{"description":"Unique permission name.","type":"string"}},"required":["id","name"],"title":"Permission","type":"object"},"PermissionGroupRef":{"additionalProperties":false,"description":"Permission group embedded inside a permission.","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"title":"PermissionGroupRef","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"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```
## Delete permission
> Permanently deletes the specified permission.\
> \
> Requires \*\*administrator\*\* access.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/permissions/{id}":{"delete":{"description":"Permanently deletes the specified permission.\n\nRequires **administrator** access.\n","operationId":"TdAuthWeb.PermissionController.delete","parameters":[{"description":"Permission ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Permission 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"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Delete permission","tags":["Permissions"]}}},"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"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```