# Service Accounts

Service account management and authentication

## GET /api/v1/service-accounts

> Returns all ServiceAccounts.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_service-accounts","description":"Service account management and authentication"}],"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_ServiceAccountList":{"type":"object","description":"Contains a list of ServiceAccounts.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/hq_ServiceAccount"}}},"required":["items"]},"hq_ServiceAccount":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"id":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactGroup"}},"token_expires_at":{"type":"string","format":"date-time","description":"If null, it won't expire."},"token_expired":{"type":"boolean"},"last_seen_at":{"type":"string","format":"date-time","description":"Updates when this service account has interaction with the API."},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","description","groups","token_expired","is_admin"]},"hq_CompactGroup":{"type":"object","description":"Represents a Group in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"sso_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"user_count":{"type":"integer","description":"Is set to the number of users in this group."},"sa_count":{"type":"integer","description":"Is set to the number of service accounts in this group."},"role_count":{"type":"integer","description":"Is set to the number of roles associated with this group."},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","user_count","sa_count","role_count"]},"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/service-accounts":{"get":{"description":"Returns all ServiceAccounts.","operationId":"listServiceAccounts","responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_ServiceAccountList"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_service-accounts"]}}}}
```

## POST /api/v1/service-accounts

> Creates a new ServiceAccount.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_service-accounts","description":"Service account management and authentication"}],"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_CreateServiceAccountRequest":{"type":"object","properties":{"name":{"type":"string","description":"Sets the unique name of the new service account. It must be a valid\nHQ resource name: it can only contain lowercase alphanumeric\ncharacters or hyphens; hyphens cannot appear at the end or start;\nthe length is 63 characters at most.\n","minLength":1,"maxLength":63,"format":"hq-resource-name"},"display_name":{"description":"Sets | the display name of the new service account. If not provided, the value of \"name\" will be used.","type":"string","minLength":1,"maxLength":150},"description":{"type":"string","description":"Sets the description of the new service account.","maxLength":250},"token_expires_at":{"type":"string","format":"date-time","description":"Determines the moment of token expiration. If not specified, the token will never expire."},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name"]},"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_ServiceAccountWithSecretToken":{"allOf":[{"$ref":"#/components/schemas/hq_ServiceAccount"},{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}]},"hq_ServiceAccount":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"id":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactGroup"}},"token_expires_at":{"type":"string","format":"date-time","description":"If null, it won't expire."},"token_expired":{"type":"boolean"},"last_seen_at":{"type":"string","format":"date-time","description":"Updates when this service account has interaction with the API."},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","description","groups","token_expired","is_admin"]},"hq_CompactGroup":{"type":"object","description":"Represents a Group in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"sso_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"user_count":{"type":"integer","description":"Is set to the number of users in this group."},"sa_count":{"type":"integer","description":"Is set to the number of service accounts in this group."},"role_count":{"type":"integer","description":"Is set to the number of roles associated with this group."},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","user_count","sa_count","role_count"]},"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/service-accounts":{"post":{"description":"Creates a new ServiceAccount.","operationId":"createServiceAccount","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_CreateServiceAccountRequest"}}}},"responses":{"201":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_ServiceAccountWithSecretToken"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_service-accounts"]}}}}
```

## GET /api/v1/service-accounts/{name}

> Returns a specific ServiceAccount.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_service-accounts","description":"Service account management and authentication"}],"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_ServiceAccount":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"id":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactGroup"}},"token_expires_at":{"type":"string","format":"date-time","description":"If null, it won't expire."},"token_expired":{"type":"boolean"},"last_seen_at":{"type":"string","format":"date-time","description":"Updates when this service account has interaction with the API."},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","description","groups","token_expired","is_admin"]},"hq_CompactGroup":{"type":"object","description":"Represents a Group in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"sso_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"user_count":{"type":"integer","description":"Is set to the number of users in this group."},"sa_count":{"type":"integer","description":"Is set to the number of service accounts in this group."},"role_count":{"type":"integer","description":"Is set to the number of roles associated with this group."},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","user_count","sa_count","role_count"]},"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/service-accounts/{name}":{"get":{"description":"Returns a specific ServiceAccount.","operationId":"getServiceAccount","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_ServiceAccount"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_service-accounts"]}}}}
```

## DELETE /api/v1/service-accounts/{name}

> Deletes a ServiceAccount.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_service-accounts","description":"Service account management and authentication"}],"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/service-accounts/{name}":{"delete":{"description":"Deletes a ServiceAccount.","operationId":"deleteServiceAccount","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_service-accounts"]}}}}
```

## PATCH /api/v1/service-accounts/{name}

> Updates a service account.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_service-accounts","description":"Service account management and authentication"}],"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_UpdateServiceAccountRequest":{"type":"object","description":"Updates a service account. Absent fields are left untouched.","properties":{"display_name":{"description":"Updates the display name of the service account.","type":"string","minLength":1,"maxLength":150},"description":{"type":"string","description":"Updates the description of a service account.","maxLength":250},"metadata":{"$ref":"#/components/schemas/hq_MetadataPatchRequest"}}},"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_ServiceAccount":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"id":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactGroup"}},"token_expires_at":{"type":"string","format":"date-time","description":"If null, it won't expire."},"token_expired":{"type":"boolean"},"last_seen_at":{"type":"string","format":"date-time","description":"Updates when this service account has interaction with the API."},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","description","groups","token_expired","is_admin"]},"hq_CompactGroup":{"type":"object","description":"Represents a Group in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"sso_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"user_count":{"type":"integer","description":"Is set to the number of users in this group."},"sa_count":{"type":"integer","description":"Is set to the number of service accounts in this group."},"role_count":{"type":"integer","description":"Is set to the number of roles associated with this group."},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","user_count","sa_count","role_count"]},"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/service-accounts/{name}":{"patch":{"description":"Updates a service account.","operationId":"updateServiceAccount","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_UpdateServiceAccountRequest"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_ServiceAccount"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_service-accounts"]}}}}
```

## POST /api/v1/service-accounts/{name}/renew-token

> Renews the service account's token. The current token is invalidated and a new one is generated. An optional expiration timestamp can be provided.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_service-accounts","description":"Service account management and authentication"}],"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_RenewServiceAccountTokenRequest":{"type":"object","properties":{"token_expires_at":{"type":"string","format":"date-time","description":"Determines the moment of token expiration. If not specified, the token will never expire."}}},"hq_ServiceAccountWithSecretToken":{"allOf":[{"$ref":"#/components/schemas/hq_ServiceAccount"},{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}]},"hq_ServiceAccount":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"id":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactGroup"}},"token_expires_at":{"type":"string","format":"date-time","description":"If null, it won't expire."},"token_expired":{"type":"boolean"},"last_seen_at":{"type":"string","format":"date-time","description":"Updates when this service account has interaction with the API."},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","description","groups","token_expired","is_admin"]},"hq_CompactGroup":{"type":"object","description":"Represents a Group in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"sso_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"user_count":{"type":"integer","description":"Is set to the number of users in this group."},"sa_count":{"type":"integer","description":"Is set to the number of service accounts in this group."},"role_count":{"type":"integer","description":"Is set to the number of roles associated with this group."},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","user_count","sa_count","role_count"]},"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/service-accounts/{name}/renew-token":{"post":{"description":"Renews the service account's token. The current token is invalidated and a new one is generated. An optional expiration timestamp can be provided.","operationId":"renewServiceAccountToken","parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_RenewServiceAccountTokenRequest"}}}},"responses":{"200":{"description":"Happy response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_ServiceAccountWithSecretToken"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_service-accounts"]}}}}
```

## PUT /api/v1/service-accounts/{name}/groups

> Assigns the given service account exactly to the provided groups, ensuring they are not part of any other groups.

```json
{"openapi":"3.0.0","info":{"title":"Lenses API","version":"6.1"},"tags":[{"name":"hq_service-accounts","description":"Service account management and authentication"}],"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_SetGroupMembershipsRequest":{"type":"object","description":"Defines the groups a user or service account should be exactly a member of.","properties":{"add_to_groups":{"description":"Adds the user or service account to the groups (specified by their names).\n","type":"array","items":{"type":"string"}},"remove_from_groups":{"description":"Removes the user or service account from the groups (specified by their names).\nIf a group is specified in both add_to_groups as well in here, removal wins.\n","type":"array","items":{"type":"string"}},"set_groups":{"type":"array","description":"Sets the user or service account memberships to those\ngroups (specified by their names) in an absolute fashion\n(ensures user/sa will be exactly a member of those), if\nprovided. Cannot be combined with the add_to_groups or remove_from_groups.\n","items":{"type":"string"}}}},"hq_ServiceAccount":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"id":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/hq_CompactGroup"}},"token_expires_at":{"type":"string","format":"date-time","description":"If null, it won't expire."},"token_expired":{"type":"boolean"},"last_seen_at":{"type":"string","format":"date-time","description":"Updates when this service account has interaction with the API."},"is_admin":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","lrn","id","created_at","description","groups","token_expired","is_admin"]},"hq_CompactGroup":{"type":"object","description":"Represents a Group in a compact way.","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"sso_name":{"type":"string"},"lrn":{"type":"string","description":"Contains the resource identifier for use in access control policies."},"id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"user_count":{"type":"integer","description":"Is set to the number of users in this group."},"sa_count":{"type":"integer","description":"Is set to the number of service accounts in this group."},"role_count":{"type":"integer","description":"Is set to the number of roles associated with this group."},"metadata":{"$ref":"#/components/schemas/hq_Metadata"}},"required":["name","display_name","sso_name","lrn","id","created_at","description","user_count","sa_count","role_count"]},"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/service-accounts/{name}/groups":{"put":{"description":"Assigns the given service account exactly to the provided groups, ensuring they are not part of any other groups.","operationId":"setServiceAccountGroupMemberships","parameters":[{"in":"path","name":"name","required":true,"description":"The name of the service account.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_SetGroupMembershipsRequest"}}}},"responses":{"200":{"description":"Service account groups membership updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_ServiceAccount"}}}},"default":{"description":"Error object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hq_Error"}}}}},"tags":["hq_service-accounts"]}}}}
```