Users
Returns all users
Happy response.
Error object.
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": "2025-08-31T09:12:37.319Z",
"groups": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-08-31T09:12:37.319Z",
"description": "text",
"user_count": 1,
"sa_count": 1,
"role_count": 1,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"last_seen_at": "2025-08-31T09:12:37.319Z",
"profile": {
"full_name": "text",
"email_address": "text"
},
"is_admin": true,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}
Creates a new user.
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.
Sets the display name of the new user. If not provided, the value of "name" will be used.
Happy response.
Error object.
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": "2025-08-31T09:12:37.319Z",
"groups": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-08-31T09:12:37.319Z",
"description": "text",
"user_count": 1,
"sa_count": 1,
"role_count": 1,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"last_seen_at": "2025-08-31T09:12:37.319Z",
"profile": {
"full_name": "text",
"email_address": "text"
},
"is_admin": true,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
Returns a specific user
Happy response.
Error object.
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": "2025-08-31T09:12:37.319Z",
"groups": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-08-31T09:12:37.319Z",
"description": "text",
"user_count": 1,
"sa_count": 1,
"role_count": 1,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"last_seen_at": "2025-08-31T09:12:37.319Z",
"profile": {
"full_name": "text",
"email_address": "text"
},
"is_admin": true,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
Updates a user.
Updates a user. Absent fields are left untouched.
Updates the display name of the user.
Happy response.
Error object.
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": "2025-08-31T09:12:37.319Z",
"groups": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-08-31T09:12:37.319Z",
"description": "text",
"user_count": 1,
"sa_count": 1,
"role_count": 1,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"last_seen_at": "2025-08-31T09:12:37.319Z",
"profile": {
"full_name": "text",
"email_address": "text"
},
"is_admin": true,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
Deletes a user.
Successful deletion.
No content
Error object.
DELETE /api/v1/users/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Allows updating fields of the user profile.
Allows changes of a user's Profile. Absent fields are left untouched.
Contains the users' full name, e.g. Mary Jane Doe.
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.
Happy response.
Error object.
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": "2025-08-31T09:12:37.319Z",
"groups": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-08-31T09:12:37.319Z",
"description": "text",
"user_count": 1,
"sa_count": 1,
"role_count": 1,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"last_seen_at": "2025-08-31T09:12:37.319Z",
"profile": {
"full_name": "text",
"email_address": "text"
},
"is_admin": true,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
Assigns the given user exactly to the provided groups, ensuring they are not part of any other groups.
The name of the user.
Defines the groups a user or service account should be exactly a member of.
Adds the user or service account to the groups (specified by their names).
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.
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.
User groups membership updated successfully.
Error object.
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": "2025-08-31T09:12:37.319Z",
"groups": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-08-31T09:12:37.319Z",
"description": "text",
"user_count": 1,
"sa_count": 1,
"role_count": 1,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"last_seen_at": "2025-08-31T09:12:37.319Z",
"profile": {
"full_name": "text",
"email_address": "text"
},
"is_admin": true,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
Returns the currently authenticated user
Happy response.
Represents either a user or service account.
Error object.
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": "2025-08-31T09:12:37.319Z",
"groups": [
{
"name": "text",
"display_name": "text",
"lrn": "text",
"id": "text",
"created_at": "2025-08-31T09:12:37.319Z",
"description": "text",
"user_count": 1,
"sa_count": 1,
"role_count": 1,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"last_seen_at": "2025-08-31T09:12:37.319Z",
"profile": {
"full_name": "text",
"email_address": "text"
},
"is_admin": true,
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
Deletes all sessions associated with the current user.
Happy response.
No content
Error object.
DELETE /api/v1/users/me/sessions HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Last updated
Was this helpful?