Users

Listing users

An API consumer can list the users of their account by issuing an HTTP GET request against this sub-resource:

/users

Verifalia replies back with an HTTP 200 (OK) status code along with a JSON object with an array of the overviews of the users. If the listing does not succeed, the API returns one of the supported HTTP error status codes and, where applicable, the details of the problem.

Verifalia returns listings of users through a JSON object which derives from the common paginated results structure, where each data item represents an overview of a specific user and has the following structure.

User overview structure

This JSON structure represents an overview of a specific user and has the following fields:

Filtering and Sorting

By default, the Verifalia API returns only non-deleted users within an account, sorted by creation date from oldest to newest; API consumers can customize this behavior by passing the following query string parameters:

Retrieving user details

API consumers can retrieve details for a specific user by sending an HTTP GET request to the following endpoint:

/users/{user-id}

Here, {user-id} is the unique identifier assigned by Verifalia when the user was created, also included when listing users.

If the request is successful, Verifalia returns an HTTP 200 (OK) status along with the user's data according to the structure described below, in JSON format. If the request fails, it responds with an appropriate HTTP error status code and, when applicable, details about the issue.

User detail structure

The user detail structure is returned as a JSON object containing the following fields:

authentication object

authentication.certificate object

authentication.password object

authorization object

Each authorization rule is represented by a string which follows this format:

[{effect}]resource[:operation[:scope]]

where:

• effect can be either an empty string (which grants permission) or a dash - (which denies permission);
• resource[:operation[:scope]] is one of the permissions the API supports;
• if the scope is not specified, it's assumed to apply account-wide;
• similarly, if the operation is not specified, all operations are assumed.

captcha object

captcha.providers object

captcha.providers.hCaptcha object

For additional details, see hCaptcha documentation.

captcha.providers.reCaptchaV2 object

For additional details, see reCAPTCHA v2 documentation.

captcha.providers.reCaptchaV2 object

For additional details, see reCAPTCHA v3 documentation.

captcha.providers.turnstile object

For additional details, see Turnstile documentation.

defaults object

firewall object

firewall.rules[] object

throttling object

throttling.rules[] object

trustedOrigin object

Verifalia supports the following wildcards:

• * matches any sequence of characters, including none;
• ? matches any single character.

Creating Users

To create a new user, API consumers must send an HTTP POST request to the following endpoint:

/users

Include a JSON payload in the request body that describes the user to be created. If the request is successful, Verifalia responds with an HTTP 200 OK status code along with a JSON object summarizing the newly created user and a Location header containing a URL where you can retrieve the full details of the user. Also, the API returns an ETag header that identifies the version of the user object, which can be used for caching and optimistic concurrency control.

If the request fails, the API responds with an appropriate HTTP error status code and, when applicable, additional details about the error.

Request Body

The request body must be a JSON object (with the Content-Type header set to application/json) and should follow the same structure as the user detail structure described above. The only additional field allowed is the user's password for authentication (not applicable to browser apps, which use passwordless authentication):

authentication.password object (additional field)

Updating users

To update an existing user, API clients should send an HTTP PATCH request to the following sub-resource:

/users/{user-id}

Here, {user-id} is the unique identifier assigned by Verifalia when the user is created, which is also included when listing or retrieving users. The request must include a payload that describes the changes to be applied.

If the update is successful, Verifalia responds with an HTTP 200 (OK) status code. If there's an error, the API returns an appropriate HTTP error status code, along with problem details when applicable.

The request body must be a JSON Patch document (as defined by RFC 6902), with the Content-Type header set to application/json-patch+json: each operation's path should target a field in the original user detail structure described above. For example, the following payload updates the user's display name:

[
  {
    "op": "replace",
    "path": "/displayName",
    "value": "Walter Hartwell White Sr."
  }
]

Deleting users

To delete a user, API clients should send an HTTP DELETE request to the following sub-resource:

/users/{user-id}

Here, {user-id} is the unique identifier assigned by Verifalia when the user was created, also included when listing or retrieving users.

If the deletion is successful, Verifalia returns an HTTP 200 (OK) status code. If the operation fails, the API responds with an appropriate HTTP error status code and, when applicable, details about the issue.