> 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/roles.md).
# Roles
## List roles
> Returns every role known by the authorization service.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles":{"get":{"description":"Returns every role known by the authorization service.\n","operationId":"TdAuthWeb.RoleController.index","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleListResponse"}}},"description":"Roles 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 roles","tags":["Roles"]}}},"components":{"schemas":{"RoleListResponse":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Role"},"type":"array"}},"required":["data"],"title":"RoleListResponse","type":"object"},"Role":{"additionalProperties":true,"description":"A role that can be granted to users or groups on a resource.","properties":{"id":{"description":"Unique role identifier.","type":"integer"},"is_default":{"description":"Whether the role is the default one. At most one role can be the default at a time.","type":"boolean"},"name":{"description":"Unique role name.","type":"string"}},"required":["id","name","is_default"],"title":"Role","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 role
> Creates a new role.\
> \
> Requires \*\*administrator\*\* access.\
> \
> If \`is\_default\` is set to \`true\`, any other role currently marked as default is automatically unset. At most one role can be the default.\
> \
> Role 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 role.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles":{"post":{"description":"Creates a new role.\n\nRequires **administrator** access.\n\nIf `is_default` is set to `true`, any other role currently marked as default is automatically unset. At most one role can be the default.\n\nRole 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 role.\n","operationId":"TdAuthWeb.RoleController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleCreateRequest"}}},"description":"Role creation payload","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleResponse"}}},"description":"Role 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 role","tags":["Roles"]}}},"components":{"schemas":{"RoleCreateRequest":{"additionalProperties":false,"description":"Payload for creating a role.\n\nIf `is_default` is set to `true`, any other role currently marked as default is automatically unset, so at most one role remains the default.\n","properties":{"role":{"additionalProperties":false,"properties":{"is_default":{"description":"Whether this role becomes the default. Defaults to `false`.","nullable":true,"type":"boolean"},"name":{"description":"Role name. Must be unique.","type":"string"}},"required":["name"],"type":"object"}},"required":["role"],"title":"RoleCreateRequest","type":"object"},"RoleResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Role"}},"required":["data"],"title":"RoleResponse","type":"object"},"Role":{"additionalProperties":true,"description":"A role that can be granted to users or groups on a resource.","properties":{"id":{"description":"Unique role identifier.","type":"integer"},"is_default":{"description":"Whether the role is the default one. At most one role can be the default at a time.","type":"boolean"},"name":{"description":"Unique role name.","type":"string"}},"required":["id","name","is_default"],"title":"Role","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 role
> Returns the specified role.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles/{id}":{"get":{"description":"Returns the specified role.","operationId":"TdAuthWeb.RoleController.show","parameters":[{"description":"Role ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleResponse"}}},"description":"Role 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 role","tags":["Roles"]}}},"components":{"schemas":{"RoleResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Role"}},"required":["data"],"title":"RoleResponse","type":"object"},"Role":{"additionalProperties":true,"description":"A role that can be granted to users or groups on a resource.","properties":{"id":{"description":"Unique role identifier.","type":"integer"},"is_default":{"description":"Whether the role is the default one. At most one role can be the default at a time.","type":"boolean"},"name":{"description":"Unique role name.","type":"string"}},"required":["id","name","is_default"],"title":"Role","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 role
> Updates the specified role.\
> \
> Requires \*\*administrator\*\* access.\
> \
> If \`is\_default\` is set to \`true\`, any other role currently marked as default is automatically unset.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles/{id}":{"put":{"description":"Updates the specified role.\n\nRequires **administrator** access.\n\nIf `is_default` is set to `true`, any other role currently marked as default is automatically unset.\n","operationId":"TdAuthWeb.RoleController.update","parameters":[{"description":"Role ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleUpdateRequest"}}},"description":"Role update payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleResponse"}}},"description":"Role 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 role","tags":["Roles"]}}},"components":{"schemas":{"RoleUpdateRequest":{"additionalProperties":false,"description":"Payload for updating a role.\n\nIf `is_default` is set to `true`, any other role currently marked as default is automatically unset.\n","properties":{"role":{"additionalProperties":false,"properties":{"is_default":{"nullable":true,"type":"boolean"},"name":{"nullable":true,"type":"string"}},"type":"object"}},"required":["role"],"title":"RoleUpdateRequest","type":"object"},"RoleResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Role"}},"required":["data"],"title":"RoleResponse","type":"object"},"Role":{"additionalProperties":true,"description":"A role that can be granted to users or groups on a resource.","properties":{"id":{"description":"Unique role identifier.","type":"integer"},"is_default":{"description":"Whether the role is the default one. At most one role can be the default at a time.","type":"boolean"},"name":{"description":"Unique role name.","type":"string"}},"required":["id","name","is_default"],"title":"Role","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 role
> Permanently deletes the specified role.\
> \
> Requires \*\*administrator\*\* access.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles/{id}":{"delete":{"description":"Permanently deletes the specified role.\n\nRequires **administrator** access.\n","operationId":"TdAuthWeb.RoleController.delete","parameters":[{"description":"Role ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Role 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 role","tags":["Roles"]}}},"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"}}}}
```
## Update role
> Updates the specified role.\
> \
> Requires \*\*administrator\*\* access.\
> \
> If \`is\_default\` is set to \`true\`, any other role currently marked as default is automatically unset.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/roles/{id}":{"patch":{"description":"Updates the specified role.\n\nRequires **administrator** access.\n\nIf `is_default` is set to `true`, any other role currently marked as default is automatically unset.\n","operationId":"TdAuthWeb.RoleController.update (2)","parameters":[{"description":"Role ID.","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleUpdateRequest"}}},"description":"Role update payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleResponse"}}},"description":"Role 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 role","tags":["Roles"]}}},"components":{"schemas":{"RoleUpdateRequest":{"additionalProperties":false,"description":"Payload for updating a role.\n\nIf `is_default` is set to `true`, any other role currently marked as default is automatically unset.\n","properties":{"role":{"additionalProperties":false,"properties":{"is_default":{"nullable":true,"type":"boolean"},"name":{"nullable":true,"type":"string"}},"type":"object"}},"required":["role"],"title":"RoleUpdateRequest","type":"object"},"RoleResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Role"}},"required":["data"],"title":"RoleResponse","type":"object"},"Role":{"additionalProperties":true,"description":"A role that can be granted to users or groups on a resource.","properties":{"id":{"description":"Unique role identifier.","type":"integer"},"is_default":{"description":"Whether the role is the default one. At most one role can be the default at a time.","type":"boolean"},"name":{"description":"Unique role name.","type":"string"}},"required":["id","name","is_default"],"title":"Role","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"}}}}
```