Skip to content

Users

Users

Query and manage users.

Only users fulfilling the conditions below will be present in the REST API.

  • User MUST have a confirmed email address.
  • User MUST be active.
  • User MUST have set the profile visibility to public.

Authentication required

Requests to search REST API endpoints require authentication. Results sets are limited to max 10 results per query (i.e. pagination is not supported).

Search users

Search for users

GET /api/users

Parameters

Name Type Location Description
q string query Search query used to filter results.
sort string query Sort search results. Customizable. Built-in options are "bestmatch", "username", "email", "domain", "newest", "oldest", "updated" (default: "bestmatch" or "newest").
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
accept string header - application/json

Sort options for users can be configured using the USERS_RESOURCES_SORT_OPTIONS config variable as described in the search customization section. Note that "bestmatch" is only available as a sort option on requests that provide a query string as a q parameter, in which case it is the default sort type. If no query string is provided in the request, the default sort type is "newest". In this case a "bestmatch" value is ignored and the default "newest" sort is used.

Query string syntax

The query string syntax is based on ElasticSearch's query string syntax.

The following search fields:

  • username
  • email
  • name or full_name or fullname
  • affiliation or affiliations

Request

GET /api/users?q=cern HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "hits": {
    "hits": [
      {
        "email": "jose.benito.gonzalez@cern.ch",
        "id": "4",
        "is_current_user": false,
        "links": {
          "avatar": "https://127.0.0.1:5000/api/users/4/avatar.svg",
          "self": "https://127.0.0.1:5000/api/users/4"
        },
        "profile": {
          "affiliations": "CERN",
          "full_name": "Jose Benito Gonzalez Lopez"
        },
        "username": "jbenito"
      },
      {
        "active": true,
        "confirmed": true,
        "created": "2022-05-23T12:03:48.466772+00:00",
        "email": "lars.holm.nielsen@cern.ch",
        "id": "3",
        "is_current_user": true,
        "links": {
          "avatar": "https://127.0.0.1:5000/api/users/3/avatar.svg",
          "self": "https://127.0.0.1:5000/api/users/3"
        },
        "preferences": {
          "email_visibility": "public",
          "visibility": "public"
        },
        "profile": {
          "affiliations": "CERN",
          "full_name": "Lars Holm Nielsen"
        },
        "revision_id": 5,
        "updated": "2022-05-23T12:04:16.204875+00:00",
        "username": "lnielsen"
      }
    ],
    "total": 2
  },
  "links": {
    "self": "https://127.0.0.1:5000/api/users"
  },
  "sortBy": "bestmatch"
}

Get a user

GET /api/users/{id}

Both authenticated and unauthenticated access is possible.

The following object-level fields are only accessible for the authenticated user themselves:

  • revision_id
  • created
  • updated
  • active
  • confirmed
  • preferences

The following fields are only accessible for if email visibility is set to public:

  • email

Parameters

Name Type Location Description
id string path The user identifier.
accept string header - application/json

Errors

  • 403: The user does not exist or the profile is not public.

Request

GET /api/users/{id} HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "3",
  "revision_id": 5,
  "created": "2022-05-23T12:03:48.466772+00:00",
  "updated": "2022-05-23T12:04:16.204875+00:00",
  "active": true,
  "confirmed": true,
  "is_current_user": true,
  "username": "lnielsen",
  "email": "lars.holm.nielsen@cern.ch",
  "profile": {
    "affiliations": "CERN",
    "full_name": "Lars Holm Nielsen"
  },
  "preferences": {
    "email_visibility": "public",
    "visibility": "public"
  },
  "links": {
    "avatar": "https://127.0.0.1:5000/api/users/3/avatar.svg",
    "self": "https://127.0.0.1:5000/api/users/3"
  }
}

Get avatar for user

GET /api/users/{id}/avatar.svg

Both authenticated and unauthenticated access is possible.

Parameters

Name Type Location Description
id string path The user identifier.

Errors

  • 403: The user does not exist or the profile is not public.

Request

GET /api/users/{id}/avatar.svg HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Disposition: inline; filename=avatar.svg
Content-Length: 351
Content-Type: image/svg+xml; charset=utf-8
ETag: "L#f06292"
...

 <svg width="256" height="256" xmlns="http://www.w3.org/2000/svg">
    <circle cx="125" cy="125" r="125" fill="#f06292" stroke="grey" />
    <text x="48%" y="53%" dominant-baseline="middle" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-size="125" fill="#f9f9f9" stroke="grey" stroke-width="2">
            L
    </text>
  </svg>

User Group Management

Group management allows administrators to assign or remove roles from a user.

Get group assignments for a user

GET /api/users/{id}/groups HTTP/1.1
Accept: application/json

Retrieves the current groups assigned to a user and, if authorized, a list of available groups that can be assigned.

Parameters

Name Type Location Description
id string path The user identifier.
accept string header - application/json

Response

{
    "available_groups": [
        {
            "description": null,
            "id": "administration",
            "is_managed": true,
            "name": "administration"
        },
        ...
    ],
    "groups": [
        {
            "id": "employee",
            "name": "employee"
        },
        {
            "id": "moderator",
            "name": "moderator"
        }
    ],
    "total": 2
}

Add groups to a user

POST /api/users/{id}/groups HTTP/1.1
Content-Type: application/json

{
  "groups": ["employee", "it-dep"]
}

Adds one or more group roles to a user. This operation is additive and does not remove existing assignments.

Parameters

Name Type Location Description
groups array body A list of group IDs or names to add.
id string path The user identifier.

Response

{
    "added": [
        "it-dep"
    ],
    "groups": [
        "employee",
        "it-dep",
        "moderator"
    ],
    "removed": []
}

Set groups for a user

PUT /api/users/{id}/groups HTTP/1.1
Content-Type: application/json

{
  "groups": ["employee"]
}

Replaces the current group assignments of a user with the provided list.

Parameters

Name Type Location Description
groups array body A list of group IDs or names to set.

*Response

{
    "added": [],
    "groups": [
        "employee",
    ],
    "removed": [
        "it-dep",
        "moderator"
    ]
}

Remove groups from a user

DELETE /api/users/{id}/groups HTTP/1.1
Content-Type: application/json

{
  "groups": ["it-dep"]
}

Removes one or more group roles from a user. This operation is destructive for the specified roles and does not affect other assignments.

Parameters

Name Type Location Description
groups array body A list of group IDs or names to remove.

Response

{
    "added": [],
    "groups": [],
    "removed": [
        "it-dep"
    ]
}