.. _list_users:

Method: List users
------------------

Description
~~~~~~~~~~~

Obtain a list of StoredSafe users, optionally search for a user by a a searchstring,
obtain a specific user by User-ID, or list all users.

Amount of details in the response, will be limited by the basic capabilities 
(:ref:`Admin or Write<bits>`) of the authenticated user, see table below.

+----------------------+-----------------------------------+-----------+-----------------+
| Attribute            | Description                       | Type      | Available to    |
+======================+===================================+===========+=================+
| id                   | User-ID                           | Integer   | Admin, Write    |
+----------------------+-----------------------------------+-----------+-----------------+
| status               | Status bits                       | Integer   | Admin           |
+----------------------+-----------------------------------+-----------+-----------------+
| username             | Username                          | String    | Admin           |
+----------------------+-----------------------------------+-----------+-----------------+
| fullname             | Fullname                          | String    | Admin, Write    |
+----------------------+-----------------------------------+-----------+-----------------+
| email                | Email                             | String    | Admin, Write    |
+----------------------+-----------------------------------+-----------+-----------------+
| otpprefix            | Yubikey Client-ID                 | String    | Admin           |
+----------------------+-----------------------------------+-----------+-----------------+
| fingerprint          | GPG Fingerprint                   | String    | Admin           |
+----------------------+-----------------------------------+-----------+-----------------+

URL Syntax
~~~~~~~~~~

/api/{version}/user |br| 
/api/{version}/user/:userid |br| 
/api/{version}/user/:searchstring |br| 

If parameter is left empty, all users will be returned.

HTTP Method
~~~~~~~~~~~

GET

Successful HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~

200

Parameters
~~~~~~~~~~

+----------------+------------------+----------------+---------+-----------+-------------------+
| Parameter name |   Description    | Parameter type |  Type   | Mandatory |      Comment      |
+================+==================+================+=========+===========+===================+
| X-Http-Token   | StoredSafe token | HTTP Header    | String  | :sup:`1)` | Preferred method  |
+----------------+------------------+----------------+---------+-----------+-------------------+
| token          | StoredSafe token | URL-parameter  | String  | :sup:`1)` | Legacy method     |
+----------------+------------------+----------------+---------+-----------+-------------------+
| user-id        | User-ID          | URL-parameter  | Integer |           |                   |
+----------------+------------------+----------------+---------+-----------+-------------------+
| searchstring   | Search string    | URL-parameter  | String  |           | Max 15 characters |
+----------------+------------------+----------------+---------+-----------+-------------------+

:sup:`\*)` One of the methods (HTTP Header or URL-parameter) is required.

Response Attributes
~~~~~~~~~~~~~~~~~~~

+---------------------+-------------------------------------------------+---------+
|      Attribute      |                   Description                   |  Type   |
+=====================+=================================================+=========+
| CALLINFO.errorcodes | Number of errors                                | Integer |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.errors     | Number of errors                                | Integer |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.general    | Information                                     | Array   |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.handler    | Handler used                                    | String  |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.status     | SUCCESS or FAIL                                 | String  |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.users.(id) | StoredSafe users                                | Array   |
+---------------------+-------------------------------------------------+---------+
| CALLINFO.token      | StoredSafe token to be used in subsequent calls | String  |
+---------------------+-------------------------------------------------+---------+
| DATA                | Supplied data in API-call                       | String  |
+---------------------+-------------------------------------------------+---------+
| HEADERS.(headers)   | HTTP Headers                                    | String  |
+---------------------+-------------------------------------------------+---------+
| PARAMS              | Route parameters (empty)                        | Array   |
+---------------------+-------------------------------------------------+---------+
| ERRORCODES          | Error code and text (Only present if errors)    | Object  |
+---------------------+-------------------------------------------------+---------+
| ERRORS              | Error code and text (Only present if errors)    | Array   |
+---------------------+-------------------------------------------------+---------+

Examples
~~~~~~~~

Search for any user matching the string "foo".

**Request**

::

   GET /api/1.0/user/foo
   x-http-token: your_storedsafe_token

**Response**

::

   {
       "CALLINFO": {
           "errorcodes": 0,
           "errors": 0,
           "general": [],
           "handler": "UserHandler",
           "status": "SUCCESS",
           "token": "rotated_storedsafe_token",
           "users": [
   			{
                   "email": "mrfoo@manchu.com",
                   "fingerprint": "F09F01DDE2AFC972078D62B3F32057A33F58AF4E",
                   "fullname": "Foo Manchu",
                   "id": "149",
                   "otpprefix": "cccjgjgkhcbb",
                   "status": "140",
                   "username": "foomanchu"
               },
               {
                   "email": "pelle@foo.com",
                   "fingerprint": "AA57179E0FC5B2DC1AB78BADACBDBCC28799F7FE",
                   "fullname": "Pelle Test",
                   "id": "109",
                   "otpprefix": "cccbkleruukb",
                   "status": "460",
                   "username": "pelle"
               }
           ]
       },
       "DATA": {
           "token": "your_storedsafe_token"
       },
       "HEADERS": {
           "Accept": "*/*",
           "Host": "safe.domain.cc",
           "User-Agent": "curl/7.64.1",
           "X-Http-Token": "your_storedsafe_token"
       },
       "PARAMS": []
   }

.. include:: ../global.rst