Method: User Certificates

Manages X.509 certificates associated with user accounts. A certificate registered here allows the user to authenticate using a smartcard (see Method: Get Smartcard User and Method: Login to StoredSafe). Each user can hold one certificate at a time.

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

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": []
}

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": []
}

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": []
}