# 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"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lenses.io/latest/api-reference/6.1/reference/service-accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.