> 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/role-permissions.md).
# Role Permissions
## List permissions associated with a role
> Returns the permissions currently associated with the specified role.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles/{role_id}/permissions":{"get":{"description":"Returns the permissions currently associated with the specified role.","operationId":"TdAuthWeb.RolePermissionController.show","parameters":[{"description":"Role ID.","in":"path","name":"role_id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionListResponse"}}},"description":"Permissions of the role"},"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":"List permissions associated with a role","tags":["Role 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"},"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"}}}}
```
## Associate a permission with a role
> Adds a permission to a role. The permission may be identified either by \`permission\_id\` or by \`permission\_name\`.\
> \
> Requires \*\*administrator\*\* access.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles/{role_id}/permissions":{"post":{"description":"Adds a permission to a role. The permission may be identified either by `permission_id` or by `permission_name`.\n\nRequires **administrator** access.\n","operationId":"TdAuthWeb.RolePermissionController.create","parameters":[{"description":"Role ID.","in":"path","name":"role_id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RolePermissionCreateRequest"}}},"description":"Permission to associate","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RolePermissionResponse"}}},"description":"Association created"},"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":"Associate a permission with a role","tags":["Role permissions"]}}},"components":{"schemas":{"RolePermissionCreateRequest":{"description":"The permission to associate may be identified either by its identifier or by its name.","oneOf":[{"$ref":"#/components/schemas/RolePermissionCreateByIdRequest"},{"$ref":"#/components/schemas/RolePermissionCreateByNameRequest"}],"title":"RolePermissionCreateRequest"},"RolePermissionCreateByIdRequest":{"additionalProperties":false,"properties":{"permission_id":{"description":"Identifier of the permission to associate.","type":"integer"}},"required":["permission_id"],"title":"RolePermissionCreateByIdRequest","type":"object"},"RolePermissionCreateByNameRequest":{"additionalProperties":false,"properties":{"permission_name":{"description":"Name of the permission to associate. Returns `404` when no permission with that name exists.","type":"string"}},"required":["permission_name"],"title":"RolePermissionCreateByNameRequest","type":"object"},"RolePermissionResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/RolePermission"}},"required":["data"],"title":"RolePermissionResponse","type":"object"},"RolePermission":{"additionalProperties":false,"description":"Association between a role and a permission.","properties":{"permission_id":{"type":"integer"},"role_id":{"type":"integer"}},"required":["role_id","permission_id"],"title":"RolePermission","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"}}}}
```
## Replace permissions associated with a role
> Replaces the full set of permissions associated with a role with the supplied list. Permissions not included in the payload are dissociated from the role.\
> \
> Requires \*\*administrator\*\* access.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles/{role_id}/permissions":{"put":{"description":"Replaces the full set of permissions associated with a role with the supplied list. Permissions not included in the payload are dissociated from the role.\n\nRequires **administrator** access.\n","operationId":"TdAuthWeb.RolePermissionController.update","parameters":[{"description":"Role ID.","in":"path","name":"role_id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RolePermissionUpdateRequest"}}},"description":"New set of permissions","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionListResponse"}}},"description":"Updated permissions of the role"},"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":"Replace permissions associated with a role","tags":["Role permissions"]}}},"components":{"schemas":{"RolePermissionUpdateRequest":{"additionalProperties":false,"description":"Replaces the full set of permissions associated with a role with the supplied list.\n\nPermissions included in the payload are associated with the role. Permissions not included are dissociated.\n","properties":{"permissions":{"description":"The complete set of permission identifiers the role should have.","items":{"additionalProperties":false,"properties":{"id":{"type":"integer"}},"required":["id"],"type":"object"},"type":"array"}},"required":["permissions"],"title":"RolePermissionUpdateRequest","type":"object"},"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"},"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"}}}}
```
## Dissociate a permission from a role
> Removes the association between a role and a permission. The permission may be identified either by \`permission\_id\` or by \`permission\_name\`.\
> \
> Requires \*\*administrator\*\* access.\
> \
> If \`permission\_name\` is supplied and no permission with that name exists, the request is rejected with \`404\`.\
> \
> If the association itself does not exist, the request is rejected with \`404\`.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles/{role_id}/permissions":{"delete":{"description":"Removes the association between a role and a permission. The permission may be identified either by `permission_id` or by `permission_name`.\n\nRequires **administrator** access.\n\nIf `permission_name` is supplied and no permission with that name exists, the request is rejected with `404`.\n\nIf the association itself does not exist, the request is rejected with `404`.\n","operationId":"TdAuthWeb.RolePermissionController.delete","parameters":[{"description":"Role ID.","in":"path","name":"role_id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RolePermissionDeleteRequest"}}},"description":"Permission to dissociate","required":false},"responses":{"204":{"description":"Association removed"},"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":"Dissociate a permission from a role","tags":["Role permissions"]}}},"components":{"schemas":{"RolePermissionDeleteRequest":{"description":"The permission to remove may be identified either by its identifier or by its name.","oneOf":[{"$ref":"#/components/schemas/RolePermissionDeleteByIdRequest"},{"$ref":"#/components/schemas/RolePermissionDeleteByNameRequest"}],"title":"RolePermissionDeleteRequest"},"RolePermissionDeleteByIdRequest":{"additionalProperties":false,"properties":{"permission_id":{"description":"Identifier of the permission to remove.","type":"integer"}},"required":["permission_id"],"title":"RolePermissionDeleteByIdRequest","type":"object"},"RolePermissionDeleteByNameRequest":{"additionalProperties":false,"properties":{"permission_name":{"description":"Name of the permission to remove. Returns `404` when no permission with that name exists.","type":"string"}},"required":["permission_name"],"title":"RolePermissionDeleteByNameRequest","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"}}}}
```
## Replace permissions associated with a role
> Replaces the full set of permissions associated with a role with the supplied list. Permissions not included in the payload are dissociated from the role.\
> \
> Requires \*\*administrator\*\* access.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles/{role_id}/permissions":{"patch":{"description":"Replaces the full set of permissions associated with a role with the supplied list. Permissions not included in the payload are dissociated from the role.\n\nRequires **administrator** access.\n","operationId":"TdAuthWeb.RolePermissionController.update (2)","parameters":[{"description":"Role ID.","in":"path","name":"role_id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RolePermissionUpdateRequest"}}},"description":"New set of permissions","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionListResponse"}}},"description":"Updated permissions of the role"},"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":"Replace permissions associated with a role","tags":["Role permissions"]}}},"components":{"schemas":{"RolePermissionUpdateRequest":{"additionalProperties":false,"description":"Replaces the full set of permissions associated with a role with the supplied list.\n\nPermissions included in the payload are associated with the role. Permissions not included are dissociated.\n","properties":{"permissions":{"description":"The complete set of permission identifiers the role should have.","items":{"additionalProperties":false,"properties":{"id":{"type":"integer"}},"required":["id"],"type":"object"},"type":"array"}},"required":["permissions"],"title":"RolePermissionUpdateRequest","type":"object"},"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"},"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"}}}}
```