# Roles

Role-based access control management

## GET /api/v1/roles

> Returns all roles.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_CompactRoleList":{"type":"object","description":"Contains a list of CompactRoles.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactRole"}}},"required":["items"]},"hq_CompactRole":{"type":"object","description":"Represents a Role in a compact way.","properties":{"name":{"description":"Holds the unique name of this role.","type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"description":{"type":"string","description":"Contains the description of the role."},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"policy_length":{"description":"Is set to the number of PermissionStatements in the Policy.","type":"integer"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy_length"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/roles":{"get":{"description":"Returns all roles.","operationId":"listRoles","responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_CompactRoleList"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```

## POST /api/v1/roles

> Creates a new role.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_CreateRoleRequest":{"type":"object","description":"Contains the fields needed to create a role.","properties":{"name":{"type":"string","description":"Sets the unique name of the new role. It must be a valid HQ\nresource name: it can only contain lowercase alphanumeric characters\nor hyphens; hyphens cannot appear at the end or start; the length is\n63 characters at most.\n","minLength":1,"maxLength":63,"format":"hq-resource-name"},"display_name":{"type":"string","description":"Sets the display name of the new role. If not provided, the value of\n\"name\" will be used.\n","minLength":1,"maxLength":150},"description":{"type":"string","description":"Sets the description of the new role.","maxLength":280},"policy":{"type":"array","description":"Contains a list of permission statements.","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","policy"]},"hq_PermissionStatement":{"type":"object","description":"Describes the effect for an action and resource.","properties":{"effect":{"$ref":"#/components/schemas/hq_PermissionEffect"},"action":{"$ref":"#/components/schemas/hq_PermissionActionScalarOrList"},"resource":{"$ref":"#/components/schemas/hq_PermissionResourceScalarOrList"}},"required":["effect","action","resource"]},"hq_PermissionEffect":{"type":"string","description":"Enumerates permission effects.","enum":["allow","deny"]},"hq_PermissionActionScalarOrList":{"description":"Is either a single action or a list of actions.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_PermissionResourceScalarOrList":{"description":"Is either a single string or a list of strings.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Role":{"type":"object","description":"Bundles a list of permission statements with a name.","properties":{"name":{"description":"Holds the unique name of this role.","type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"description":{"type":"string","description":"Contains the description of the role."},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"policy":{"type":"array","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy"]},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/roles":{"post":{"description":"Creates a new role.","operationId":"createRole","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_CreateRoleRequest"}}}},"responses":{"201":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Role"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```

## POST /api/v1/roles/{name}/policy

> Adds a permission statement to an existing Role's policy. No deduplication is done.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_PermissionStatement":{"type":"object","description":"Describes the effect for an action and resource.","properties":{"effect":{"$ref":"#/components/schemas/hq_PermissionEffect"},"action":{"$ref":"#/components/schemas/hq_PermissionActionScalarOrList"},"resource":{"$ref":"#/components/schemas/hq_PermissionResourceScalarOrList"}},"required":["effect","action","resource"]},"hq_PermissionEffect":{"type":"string","description":"Enumerates permission effects.","enum":["allow","deny"]},"hq_PermissionActionScalarOrList":{"description":"Is either a single action or a list of actions.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_PermissionResourceScalarOrList":{"description":"Is either a single string or a list of strings.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_Role":{"type":"object","description":"Bundles a list of permission statements with a name.","properties":{"name":{"description":"Holds the unique name of this role.","type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"description":{"type":"string","description":"Contains the description of the role."},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"policy":{"type":"array","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/roles/{name}/policy":{"post":{"description":"Adds a permission statement to an existing Role's policy. No deduplication is done.","operationId":"addPermissionStatementToRole","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_PermissionStatement"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Role"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```

## GET /api/v1/roles/{name}

> Returns a specific role.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Role":{"type":"object","description":"Bundles a list of permission statements with a name.","properties":{"name":{"description":"Holds the unique name of this role.","type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"description":{"type":"string","description":"Contains the description of the role."},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"policy":{"type":"array","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy"]},"hq_PermissionStatement":{"type":"object","description":"Describes the effect for an action and resource.","properties":{"effect":{"$ref":"#/components/schemas/hq_PermissionEffect"},"action":{"$ref":"#/components/schemas/hq_PermissionActionScalarOrList"},"resource":{"$ref":"#/components/schemas/hq_PermissionResourceScalarOrList"}},"required":["effect","action","resource"]},"hq_PermissionEffect":{"type":"string","description":"Enumerates permission effects.","enum":["allow","deny"]},"hq_PermissionActionScalarOrList":{"description":"Is either a single action or a list of actions.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_PermissionResourceScalarOrList":{"description":"Is either a single string or a list of strings.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/roles/{name}":{"get":{"description":"Returns a specific role.","operationId":"getRole","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Role"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```

## DELETE /api/v1/roles/{name}

> Deletes a role.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/roles/{name}":{"delete":{"description":"Deletes a role.","operationId":"deleteRole","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Successful deletion."},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```

## PATCH /api/v1/roles/{name}

> Updates a role.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_roles","description":"Role-based access control management"}],"servers":[{"url":"{server}","variables":{"server":{"default":"https://api.example.com"}}}],"security":[{"bearerAuth":[]},{"cookieAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The bearer token can be obtained by creating a ServiceAccount.\n"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"session_id","description":"On successful SAML/SSO login, the API will set a cookie with a session id.\n"}},"schemas":{"hq_UpdateRoleRequest":{"type":"object","description":"Updates a role. Absent fields are left untouched.","properties":{"display_name":{"type":"string","description":"Updates the display name of the role.","minLength":1,"maxLength":150},"description":{"type":"string","description":"Updates the description of the role.","maxLength":280},"policy":{"type":"array","description":"Sets, if specififed, the new permission statements.","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_MetadataPatchRequest"}}},"hq_PermissionStatement":{"type":"object","description":"Describes the effect for an action and resource.","properties":{"effect":{"$ref":"#/components/schemas/hq_PermissionEffect"},"action":{"$ref":"#/components/schemas/hq_PermissionActionScalarOrList"},"resource":{"$ref":"#/components/schemas/hq_PermissionResourceScalarOrList"}},"required":["effect","action","resource"]},"hq_PermissionEffect":{"type":"string","description":"Enumerates permission effects.","enum":["allow","deny"]},"hq_PermissionActionScalarOrList":{"description":"Is either a single action or a list of actions.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_PermissionResourceScalarOrList":{"description":"Is either a single string or a list of strings.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"type":"string"}}]},"hq_MetadataPatchRequest":{"type":"object","description":"Patches metadata. It has the following semantics:\n  - Absent keys are left untouched;\n  - Null values are deleted;\n  - Non-null values are replaced.\n","additionalProperties":{"type":"string","nullable":true}},"hq_Role":{"type":"object","description":"Bundles a list of permission statements with a name.","properties":{"name":{"description":"Holds the unique name of this role.","type":"string"},"display_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"description":{"type":"string","description":"Contains the description of the role."},"id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"policy":{"type":"array","items":{"$ref":"#/components/schemas/hq_PermissionStatement"}},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","description","id","created_at","policy"]},"hq_Metadata":{"type":"object","description":"Allows attaching custom string key/values to resources.\nThe following maxima apply:\n- 50 keys/values;\n- 40 bytes key length;\n- 500 bytes value length.\n","additionalProperties":{"type":"string"}},"hq_Error":{"type":"object","description":"Implements the RFC7807 \"Problem Details\", see https://www.rfc-editor.org/rfc/rfc7807.","properties":{"type":{"$ref":"#/components/schemas/hq_ErrorType"},"title":{"description":"Describes the problem in a human readable fashion.","type":"string"},"status":{"description":"Is a copy of the http status code.","type":"integer"},"invalid_fields":{"description":"Lists for validation errors the fields that failed validation.","type":"array","items":{"$ref":"#/components/schemas/hq_InvalidField"}},"sso_url":{"description":"Contains in case of an \"unauthorised\" type of error, the url of the SSO provider, if any.","type":"string"},"request_id":{"description":"Is set to the id of this request. Can be used to correlate backend logs.","type":"string"}},"required":["status","title"]},"hq_ErrorType":{"type":"string","description":"Enumerates possible error types.","enum":["not_found","unauthorised","forbidden","internal_server_error","agent_rpc_error","missing_agent_capabilities","agent_not_connected","validation_error","invalid_metadata","missing_parameter","invalid_parameter","licence_limitation","ai_server_unavailable","conflict","unspecified"]},"hq_InvalidField":{"type":"object","properties":{"name":{"type":"string"},"error":{"$ref":"#/components/schemas/hq_FieldErrorType"},"title":{"type":"string"},"pointer":{"description":"Holds a RFC-6901 JSON Pointer.","type":"string"}},"required":["name","error","title"]},"hq_FieldErrorType":{"type":"string","description":"Enumerates field validation error types.","enum":["reference_not_found","not_unique","invalid_value","other_error"]}}},"paths":{"/api/v1/roles/{name}":{"patch":{"description":"Updates a role.","operationId":"updateRole","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_UpdateRoleRequest"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Role"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_roles"]}}}}
```