Users | Lenses Docs

Products Download Community Edition

get

Returns a specific user

Authorizations

Path parameters

namestringRequired

Responses

200

Happy response.

application/json

default

Error object.

application/json

get

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-06-10T22:33:03.438Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-06-10T22:33:03.438Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-06-10T22:33:03.438Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

delete

Deletes a user.

Authorizations

Path parameters

namestringRequired

Responses

204

Successful deletion.

default

Error object.

application/json

delete

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

No content

get

Returns the currently authenticated user

Authorizations

Responses

200

Happy response.

application/json

Responseone of

Represents either a user or service account.

default

Error object.

application/json

get

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-06-10T22:33:03.438Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-06-10T22:33:03.438Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-06-10T22:33:03.438Z",
  "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

Responses

204

Happy response.

default

Error object.

application/json

delete

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

No content

get

Returns all users

Authorizations

Responses

200

Happy response.

application/json

default

Error object.

application/json

get

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-06-10T22:33:03.438Z",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-06-10T22:33:03.438Z",
          "description": "text",
          "user_count": 1,
          "sa_count": 1,
          "role_count": 1,
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ],
      "last_seen_at": "2025-06-10T22:33:03.438Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

post

Creates a new user.

Authorizations

Body

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

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-06-10T22:33:03.438Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-06-10T22:33:03.438Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-06-10T22:33:03.438Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

patch

Updates a user.

Authorizations

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

default

Error object.

application/json

patch

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-06-10T22:33:03.438Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-06-10T22:33:03.438Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-06-10T22:33:03.438Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

patch

Allows updating fields of the user profile.

Authorizations

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. mary.jane@doe.net. 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

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-06-10T22:33:03.438Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-06-10T22:33:03.438Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-06-10T22:33:03.438Z",
  "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

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

default

Error object.

application/json

put

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-06-10T22:33:03.438Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-06-10T22:33:03.438Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-06-10T22:33:03.438Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}