.. _user_certificates:

Method: User Certificates
--------------------------

Manages X.509 certificates associated with user accounts. A certificate registered
here allows the user to authenticate using a smartcard (see :ref:`authinfo_smcuser`
and :ref:`login`). Each user can hold one certificate at a time.

Retrieving and deleting certificates requires admin privileges, except when
retrieving your own certificate.

.. _usercert_get:

Get Certificate
~~~~~~~~~~~~~~~

Description
^^^^^^^^^^^

Returns the parsed X.509 certificate registered on a user. Admins may fetch
any user's certificate by supplying a ``user-id``; non-admins always get their
own certificate regardless of any supplied ID.

URL Syntax
^^^^^^^^^^

/api/{version}/usercert

/api/{version}/usercert/:user-id

HTTP Method
^^^^^^^^^^^

GET

Successful HTTP Response
^^^^^^^^^^^^^^^^^^^^^^^^^

200

Parameters
^^^^^^^^^^

+----------------+-----------------------------------+----------------+---------+-----------+-------------------------------+
| Parameter name | Description                       | Parameter type | Type    | Mandatory | Comment                       |
+================+===================================+================+=========+===========+===============================+
| X-Http-Token   | StoredSafe token                  | HTTP Header    | String  | Yes       |                               |
+----------------+-----------------------------------+----------------+---------+-----------+-------------------------------+
| user-id        | Target user ID                    | URL-parameter  | Integer | No        | Admin only; own ID if omitted |
+----------------+-----------------------------------+----------------+---------+-----------+-------------------------------+

Response Attributes
^^^^^^^^^^^^^^^^^^^

+---------------------+--------------------------------------------------+---------+
| Attribute           | Description                                      | Type    |
+=====================+==================================================+=========+
| CALLINFO.status     | SUCCESS or FAIL                                  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.token      | StoredSafe token to be used in subsequent calls  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.handler    | Handler used                                     | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errors     | Number of errors                                 | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errorcodes | Number of error codes                            | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.certificate| Parsed certificate fields                        | Object  |
+---------------------+--------------------------------------------------+---------+

Example
^^^^^^^

**Request**

::

    GET /api/1.0/usercert/42
    X-Http-Token: your_storedsafe_token

**Response**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "UserCertHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token",
            "certificate": {
                "subject": {
                    "CN": "Alice Example",
                    "O":  "Example AB",
                    "C":  "SE"
                },
                "validFrom": "2024-01-01T00:00:00Z",
                "validTo":   "2026-01-01T00:00:00Z"
            }
        },
        "DATA": { ... },
        "HEADERS": { ... },
        "PARAMS": []
    }

.. _usercert_post:

Add Certificate
~~~~~~~~~~~~~~~

Description
^^^^^^^^^^^

Registers an X.509 user certificate on a user account, enabling smartcard
authentication for that user. Requires admin privileges. The certificate must
be a PEM-encoded user certificate uploaded as a multipart file.

The certificate must not already be registered to another user account.

URL Syntax
^^^^^^^^^^

/api/{version}/usercert/:user-id

HTTP Method
^^^^^^^^^^^

POST

Successful HTTP Response
^^^^^^^^^^^^^^^^^^^^^^^^^

200

Parameters
^^^^^^^^^^

+----------------+-------------------------------------------+----------------+---------+-----------+
| Parameter name | Description                               | Parameter type | Type    | Mandatory |
+================+===========================================+================+=========+===========+
| X-Http-Token   | StoredSafe token                          | HTTP Header    | String  | Yes       |
+----------------+-------------------------------------------+----------------+---------+-----------+
| user-id        | Target user ID                            | URL-parameter  | Integer | Yes       |
+----------------+-------------------------------------------+----------------+---------+-----------+
| (file)         | PEM-encoded X.509 user certificate (.cer) | multipart/form | File    | Yes       |
+----------------+-------------------------------------------+----------------+---------+-----------+

Response Attributes
^^^^^^^^^^^^^^^^^^^

+---------------------+--------------------------------------------------+---------+
| Attribute           | Description                                      | Type    |
+=====================+==================================================+=========+
| CALLINFO.status     | SUCCESS or FAIL                                  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.token      | StoredSafe token to be used in subsequent calls  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.handler    | Handler used                                     | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errors     | Number of errors                                 | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errorcodes | Number of error codes                            | Integer |
+---------------------+--------------------------------------------------+---------+

Example
^^^^^^^

**Request**

::

    POST /api/1.0/usercert/42
    X-Http-Token: your_storedsafe_token
    Content-Type: multipart/form-data; boundary=Boundary123

    --Boundary123
    Content-Disposition: form-data; name="file"; filename="alice.cer"
    Content-Type: application/x-x509-user-cert

    (PEM certificate data)
    --Boundary123--

**Response**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "UserCertHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": { ... },
        "HEADERS": { ... },
        "PARAMS": []
    }

.. _usercert_delete:

Remove Certificate
~~~~~~~~~~~~~~~~~~

Description
^^^^^^^^^^^

Removes the X.509 certificate registered on a user account, disabling smartcard
authentication for that user. Requires admin privileges.

URL Syntax
^^^^^^^^^^

/api/{version}/usercert/:user-id

HTTP Method
^^^^^^^^^^^

DELETE

Successful HTTP Response
^^^^^^^^^^^^^^^^^^^^^^^^^

200

Parameters
^^^^^^^^^^

+----------------+-----------------------------------+----------------+---------+-----------+
| Parameter name | Description                       | Parameter type | Type    | Mandatory |
+================+===================================+================+=========+===========+
| X-Http-Token   | StoredSafe token                  | HTTP Header    | String  | Yes       |
+----------------+-----------------------------------+----------------+---------+-----------+
| user-id        | Target user ID                    | URL-parameter  | Integer | Yes       |
+----------------+-----------------------------------+----------------+---------+-----------+

Example
^^^^^^^

**Request**

::

    DELETE /api/1.0/usercert/42
    X-Http-Token: your_storedsafe_token

**Response**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "UserCertHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": { ... },
        "HEADERS": { ... },
        "PARAMS": []
    }