Users

User account management

get

Returns all users

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

200

Happy response.

application/json

Contains a list of Users.

default

Error object.

application/json

get/api/v1/users

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

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "sso_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2026-01-01T00:00:00.000Z",
          "description": "text",
          "user_count": 1,
          "sa_count": 1,
          "role_count": 1,
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ],
      "last_seen_at": "2026-01-01T00:00:00.000Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

post

Creates a new user.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Body

namestring · min: 1 · max: 100Required

Sets the unique name of the new user.

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

Models an HQ user.

namestringRequired

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

last_seen_atstring · date-timeOptional

Updates when this user has interaction with the API.

is_adminbooleanRequired

default

Error object.

application/json

post/api/v1/users

POST /api/v1/users HTTP/1.1
Host: api.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": "2026-01-01T00:00:00.000Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2026-01-01T00:00:00.000Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

get

Returns a specific user

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

200

Happy response.

application/json

Models an HQ user.

namestringRequired

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

last_seen_atstring · date-timeOptional

Updates when this user has interaction with the API.

is_adminbooleanRequired

default

Error object.

application/json

get/api/v1/users/{name}

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

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2026-01-01T00:00:00.000Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

delete

Deletes a user.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Responses

204

Successful deletion.

No content

default

Error object.

application/json

delete/api/v1/users/{name}

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

No content

patch

Updates a user.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

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

Models an HQ user.

namestringRequired

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

last_seen_atstring · date-timeOptional

Updates when this user has interaction with the API.

is_adminbooleanRequired

default

Error object.

application/json

patch/api/v1/users/{name}

PATCH /api/v1/users/{name} HTTP/1.1
Host: api.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": "2026-01-01T00:00:00.000Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2026-01-01T00:00:00.000Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

patch

Allows updating fields of the user profile.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

Body

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. [e-mail]. 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

Models an HQ user.

namestringRequired

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

last_seen_atstring · date-timeOptional

Updates when this user has interaction with the API.

is_adminbooleanRequired

default

Error object.

application/json

patch/api/v1/users/{name}/profile

PATCH /api/v1/users/{name}/profile HTTP/1.1
Host: api.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": "2026-01-01T00:00:00.000Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2026-01-01T00:00:00.000Z",
  "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

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters

namestringRequired

The name of the user.

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

User groups membership updated successfully.

application/json

Models an HQ user.

namestringRequired

Contains the canonical and unique user's user name. Potentially an implicit reference to a corresponding entity in an external system in case of SSO.

display_namestringRequired

lrnstringRequired

Contains the resource identifier for use in access control policies.

idstringRequired

created_atstring · date-timeRequired

last_seen_atstring · date-timeOptional

Updates when this user has interaction with the API.

is_adminbooleanRequired

default

Error object.

application/json

put/api/v1/users/{name}/groups

PUT /api/v1/users/{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",
  "lrn": "text",
  "id": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2026-01-01T00:00:00.000Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

get

Returns the currently authenticated user

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

200

Happy response.

application/json

Represents either a user or service account.

or

default

Error object.

application/json

get/api/v1/users/me

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

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "sso_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2026-01-01T00:00:00.000Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

get

Returns the current user's settings.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

200

Happy response.

application/json

Models a user's settings.

default

Error object.

application/json

get/api/v1/users/me/settings

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

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

patch

Allows updating fields of the current user's settings.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Body

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

Responses

200

Happy response.

application/json

Models a user's settings.

default

Error object.

application/json

patch/api/v1/users/me/settings

PATCH /api/v1/users/me/settings HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

delete

Deletes all sessions associated with the current user.

Authorizations

AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses

204

Happy response.

No content

default

Error object.

application/json

delete/api/v1/users/me/sessions

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

No content