Users

get

Returns all users

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

/v1/users

HTTPcURLJavaScriptPython

GET /api/v1/users HTTP/1.1
Host: https:/.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-16T22:14:48.920Z",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-12-16T22:14:48.920Z",
          "description": "text",
          "user_count": 1,
          "sa_count": 1,
          "role_count": 1,
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ],
      "last_seen_at": "2025-12-16T22:14:48.920Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

post

Creates a new user.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Body

application/json

namestring · min: 1 · max: 100Required

Sets the unique name of the new user. 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 user. If not provided, the value of "name" will be used.

Responses

201

Happy response.

application/json

default

Error object.

application/json

post

/v1/users

HTTPcURLJavaScriptPython

POST /api/v1/users HTTP/1.1
Host: https:/.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83

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

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-12-16T22:14:48.920Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-16T22:14:48.920Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-12-16T22:14:48.920Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

get

Returns a specific user

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

/v1/users/{name}

HTTPcURLJavaScriptPython

GET /api/v1/users/{name} HTTP/1.1
Host: https:/.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-12-16T22:14:48.920Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-16T22:14:48.920Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-12-16T22:14:48.920Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

patch

Updates a user.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

application/json

Updates a user. Absent fields are left untouched.

display_namestring · min: 1 · max: 150Optional

Updates the display name of the user.

Responses

200

Happy response.

application/json

default

Error object.

application/json

patch

/v1/users/{name}

HTTPcURLJavaScriptPython

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

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

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-12-16T22:14:48.920Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-16T22:14:48.920Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-12-16T22:14:48.920Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

delete

Deletes a user.

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

/v1/users/{name}

HTTPcURLJavaScriptPython

DELETE /api/v1/users/{name} HTTP/1.1
Host: https:/.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

patch

Allows updating fields of the user profile.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

application/json

Allows changes of a user's Profile. Absent fields are left untouched.

full_namestring · max: 100Optional

Contains the users' full name, e.g. Mary Jane Doe.

email_addressstring · max: 100Optional

Contains the users' email address, e.g. [email protected]. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

Responses

200

Happy response.

application/json

default

Error object.

application/json

patch

/v1/users/{name}/profile

HTTPcURLJavaScriptPython

PATCH /api/v1/users/{name}/profile HTTP/1.1
Host: https:/.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "full_name": "text",
  "email_address": "text"
}

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-12-16T22:14:48.920Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-16T22:14:48.920Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-12-16T22:14:48.920Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

put

Assigns the given user 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 user.

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

User groups membership updated successfully.

application/json

default

Error object.

application/json

put

/v1/users/{name}/groups

HTTPcURLJavaScriptPython

PUT /api/v1/users/{name}/groups HTTP/1.1
Host: https:/.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",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-12-16T22:14:48.920Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-16T22:14:48.920Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-12-16T22:14:48.920Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

get

Returns the currently authenticated user

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

200

Happy response.

application/json

Responseone of

Represents either a user or service account.

or

default

Error object.

application/json

get

/v1/users/me

HTTPcURLJavaScriptPython

GET /api/v1/users/me HTTP/1.1
Host: https:/.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-12-16T22:14:48.920Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-12-16T22:14:48.920Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-12-16T22:14:48.920Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

delete

Deletes all sessions associated with the current user.

Authorizations

bearerAuthcookieAuth

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

204

Happy response.

default

Error object.

application/json

delete

/v1/users/me/sessions

HTTPcURLJavaScriptPython

DELETE /api/v1/users/me/sessions HTTP/1.1
Host: https:/.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content