Service Accounts

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

PUThttps://api.example.com/api/v1/service-accounts/{name}/groups

Path parameters

name*string

The name of the service account.

Body

add_to_groupsarray of string

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

remove_from_groupsarray of string

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_groupsarray of string

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.

Response

Service account groups membership updated successfully.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Request

const response = await fetch('https://api.example.com/api/v1/service-accounts/{name}/groups', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T13:40:14.347Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T13:40:14.347Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T13:40:14.347Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T13:40:14.347Z",
  "is_admin": false
}

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

POSThttps://api.example.com/api/v1/service-accounts/{name}/renew-token

Path parameters

name*string

Body

token_expires_atstring (date-time)

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

Response

Happy response.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

token*string

Request

const response = await fetch('https://api.example.com/api/v1/service-accounts/{name}/renew-token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T13:40:14.347Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T13:40:14.347Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T13:40:14.347Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T13:40:14.347Z",
  "is_admin": false,
  "token": "text"
}

Deletes a ServiceAccount.

DELETEhttps://api.example.com/api/v1/service-accounts/{name}

Path parameters

name*string

Response

Successful deletion.

Request

const response = await fetch('https://api.example.com/api/v1/service-accounts/{name}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "type": "not_found",
  "title": "text",
  "status": 0,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}

Updates a service account.

PATCHhttps://api.example.com/api/v1/service-accounts/{name}

Path parameters

name*string

Body

display_namestring

Updates the display name of the service account.

descriptionstring

Updates the description of a service account.

metadataMetadataPatchRequest (object)

Patches metadata. It has the following semantics:

Absent keys are left untouched;
Null values are deleted;
Non-null values are replaced.

Response

Happy response.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Request

const response = await fetch('https://api.example.com/api/v1/service-accounts/{name}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T13:40:14.347Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T13:40:14.347Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T13:40:14.347Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T13:40:14.347Z",
  "is_admin": false
}

Returns a specific ServiceAccount.

GEThttps://api.example.com/api/v1/service-accounts/{name}

Path parameters

name*string

Response

Happy response.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Request

const response = await fetch('https://api.example.com/api/v1/service-accounts/{name}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T13:40:14.347Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T13:40:14.347Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T13:40:14.347Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T13:40:14.347Z",
  "is_admin": false
}

Creates a new ServiceAccount.

POSThttps://api.example.com/api/v1/service-accounts

Body

name*string (hq-resource-name)

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

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

descriptionstring

Sets the description of the new service account.

token_expires_atstring (date-time)

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

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

Response

Happy response.

Body

name*string

display_name*string

id*string

lrn*string

Contains the resource identifier for use in access control policies.

created_at*string (date-time)

description*string

groups*array of CompactGroup (object)

token_expires_atstring (date-time)

If null, it won't expire.

token_expired*boolean

last_seen_atstring (date-time)

Updates when this service account has interaction with the API.

is_admin*boolean

metadataMetadata (object)

Allows attaching custom string key/values to resources. The following maxima apply:

50 keys/values;
40 bytes key length;
500 bytes value length.

token*string

Request

const response = await fetch('https://api.example.com/api/v1/service-accounts', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text"
    }),
});
const data = await response.json();

Response

{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-01-17T13:40:14.347Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-01-17T13:40:14.347Z",
      "description": "text",
      "user_count": 0,
      "sa_count": 0,
      "role_count": 0
    }
  ],
  "token_expires_at": "2025-01-17T13:40:14.347Z",
  "token_expired": false,
  "last_seen_at": "2025-01-17T13:40:14.347Z",
  "is_admin": false,
  "token": "text"
}

Returns all ServiceAccounts.

GEThttps://api.example.com/api/v1/service-accounts

Response

Happy response.

Body

items*array of ServiceAccount (object)

Request

const response = await fetch('https://api.example.com/api/v1/service-accounts', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "id": "text",
      "lrn": "text",
      "created_at": "2025-01-17T13:40:14.347Z",
      "description": "text",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-01-17T13:40:14.347Z",
          "description": "text",
          "user_count": 0,
          "sa_count": 0,
          "role_count": 0
        }
      ],
      "token_expires_at": "2025-01-17T13:40:14.347Z",
      "token_expired": false,
      "last_seen_at": "2025-01-17T13:40:14.347Z",
      "is_admin": false
    }
  ]
}

PreviousRoles NextEnvironments

Last updated 1 month ago

const response = await fetch('https://api.example.com/api/v1/service-accounts/{name}/groups', { method: 'PUT', headers: { "Content-Type": "application/json" }, body: JSON.stringify({}), }); const data = await response.json();

{ "name": "text", "display_name": "text", "id": "text", "lrn": "text", "created_at": "2025-01-17T13:40:14.347Z", "description": "text", "groups": [ { "name": "text", "display_name": "text", "lrn": "text", "id": "text", "created_at": "2025-01-17T13:40:14.347Z", "description": "text", "user_count": 0, "sa_count": 0, "role_count": 0 } ], "token_expires_at": "2025-01-17T13:40:14.347Z", "token_expired": false, "last_seen_at": "2025-01-17T13:40:14.347Z", "is_admin": false }

const response = await fetch('https://api.example.com/api/v1/service-accounts', { method: 'POST', headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "name": "text" }), }); const data = await response.json();