Service Accounts

Service account management and authentication

get

Returns all ServiceAccounts.

Authorizations

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

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-11-15T12:27:16.904Z",
      "description": "text",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "sso_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-11-15T12:27:16.904Z",
          "description": "text",
          "user_count": 1,
          "sa_count": 1,
          "role_count": 1,
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ],
      "token_expires_at": "2025-11-15T12:27:16.904Z",
      "token_expired": true,
      "last_seen_at": "2025-11-15T12:27:16.904Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

post

Creates a new ServiceAccount.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Body

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

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-11-15T12:27:16.904Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-11-15T12:27:16.904Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-11-15T12:27:16.904Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-11-15T12:27:16.904Z",
  "token_expired": true,
  "last_seen_at": "2025-11-15T12:27:16.904Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "token": "text"
}

get

Returns a specific ServiceAccount.

Authorizations

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}

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-11-15T12:27:16.904Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-11-15T12:27:16.904Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-11-15T12:27:16.904Z",
  "token_expired": true,
  "last_seen_at": "2025-11-15T12:27:16.904Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

delete

Deletes a ServiceAccount.

Authorizations

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}

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

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

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}

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-11-15T12:27:16.904Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-11-15T12:27:16.904Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-11-15T12:27:16.904Z",
  "token_expired": true,
  "last_seen_at": "2025-11-15T12:27:16.904Z",
  "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

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

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

Responseall of

default

Error object.

application/json

post

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

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-11-15T12:27:16.904Z"
}

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-11-15T12:27:16.904Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-11-15T12:27:16.904Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-11-15T12:27:16.904Z",
  "token_expired": true,
  "last_seen_at": "2025-11-15T12:27:16.904Z",
  "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

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

The name of the service account.

Body

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

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-11-15T12:27:16.904Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-11-15T12:27:16.904Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-11-15T12:27:16.904Z",
  "token_expired": true,
  "last_seen_at": "2025-11-15T12:27:16.904Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

PreviousUsers NextGroups

Last updated 6 days ago

Was this helpful?

Good afternoon