Service Accounts

Service account management and authentication

get

Returns all ServiceAccounts.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

200

Happy response.

application/json

default

Error object.

application/json

get

/api/v1/service-accounts

HTTPcURLJavaScriptPython

GET /api/v1/service-accounts HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "id": "text",
      "lrn": "text",
      "created_at": "2025-12-29T11:50:38.957Z",
      "description": "text",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "sso_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-12-29T11:50:38.957Z",
          "description": "text",
          "user_count": 1,
          "sa_count": 1,
          "role_count": 1,
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ],
      "token_expires_at": "2025-12-29T11:50:38.957Z",
      "token_expired": true,
      "last_seen_at": "2025-12-29T11:50:38.957Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

post

Creates a new ServiceAccount.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Body

application/json

namestring · hq-resource-name · min: 1 · max: 63Required

Sets the unique name of the new service account. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring · min: 1 · max: 150Optional

Sets | the display name of the new service account. If not provided, the value of "name" will be used.

descriptionstring · max: 250Optional

Sets the description of the new service account.

token_expires_atstring · date-timeOptional

Determines the moment of token expiration. If not specified, the token will never expire.

Responses

201

Happy response.

application/json

default

Error object.

application/json

post

/api/v1/service-accounts

HTTPcURLJavaScriptPython

POST /api/v1/service-accounts HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 150

{
  "name": "text",
  "display_name": "text",
  "description": "text",
  "token_expires_at": "2025-12-29T11:50:38.957Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-12-29T11:50:38.957Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-29T11:50:38.957Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-12-29T11:50:38.957Z",
  "token_expired": true,
  "last_seen_at": "2025-12-29T11:50:38.957Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "token": "text"
}

get

Returns a specific ServiceAccount.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

200

Happy response.

application/json

default

Error object.

application/json

get

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

HTTPcURLJavaScriptPython

GET /api/v1/service-accounts/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-12-29T11:50:38.957Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-29T11:50:38.957Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-12-29T11:50:38.957Z",
  "token_expired": true,
  "last_seen_at": "2025-12-29T11:50:38.957Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

delete

Deletes a ServiceAccount.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

204

Successful deletion.

default

Error object.

application/json

delete

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

HTTPcURLJavaScriptPython

DELETE /api/v1/service-accounts/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

patch

Updates a service account.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

application/json

Updates a service account. Absent fields are left untouched.

display_namestring · min: 1 · max: 150Optional

Updates the display name of the service account.

descriptionstring · max: 250Optional

Updates the description of a service account.

Responses

200

Happy response.

application/json

default

Error object.

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /api/v1/service-accounts/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "display_name": "text",
  "description": "text",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-12-29T11:50:38.957Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-29T11:50:38.957Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-12-29T11:50:38.957Z",
  "token_expired": true,
  "last_seen_at": "2025-12-29T11:50:38.957Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

post

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

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

application/json

token_expires_atstring · date-timeOptional

Determines the moment of token expiration. If not specified, the token will never expire.

Responses

200

Happy response.

application/json

default

Error object.

application/json

post

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

HTTPcURLJavaScriptPython

POST /api/v1/service-accounts/{name}/renew-token HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "token_expires_at": "2025-12-29T11:50:38.957Z"
}

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-12-29T11:50:38.957Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-29T11:50:38.957Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-12-29T11:50:38.957Z",
  "token_expired": true,
  "last_seen_at": "2025-12-29T11:50:38.957Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "token": "text"
}

put

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

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

The name of the service account.

Body

application/json

Defines the groups a user or service account should be exactly a member of.

add_to_groupsstring[]Optional

Adds the user or service account to the groups (specified by their names).

remove_from_groupsstring[]Optional

Removes the user or service account from the groups (specified by their names). If a group is specified in both add_to_groups as well in here, removal wins.

set_groupsstring[]Optional

Sets the user or service account memberships to those groups (specified by their names) in an absolute fashion (ensures user/sa will be exactly a member of those), if provided. Cannot be combined with the add_to_groups or remove_from_groups.

Responses

200

Service account groups membership updated successfully.

application/json

default

Error object.

application/json

put

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

HTTPcURLJavaScriptPython

PUT /api/v1/service-accounts/{name}/groups HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "add_to_groups": [
    "text"
  ],
  "remove_from_groups": [
    "text"
  ],
  "set_groups": [
    "text"
  ]
}

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-12-29T11:50:38.957Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-29T11:50:38.957Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-12-29T11:50:38.957Z",
  "token_expired": true,
  "last_seen_at": "2025-12-29T11:50:38.957Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}