Bearer authentication
Under this authentication method Verifalia provides you with an encrypted security token (called
bearer token) in response to a first authentication request, using the user-name and
password of either an administrator (inadvisable for security reasons, see
above) or a standard user bound to your Verifalia account; the API consumer must then send that encrypted
security token while making subsequent requests.
Bearer authentication offers higher security over HTTP Basic Auth, as the
latter requires sending the actual credentials on each API call, while the former only
requires it on a first, dedicated authentication request. On the other side, the first
authentication request needed by Bearer authentication takes a non-negligible time: if
the API consumer needs to perform only one request, using HTTP Basic Auth provides the
same degree of security and is the faster option too.
v2.6+ The bearer tokens provided
by Verifalia are JSON Web Tokens (JWTs), adhering to the open standard defined by RFC 7519; this standard offers a concise and self-contained method for securely transmitting information
between parties in the form of a JSON object. The JSON object structure contains several fields
the standard calls claims, including sub
, exp
, and other custom claims as documented below;
additionally, it may contain other fields subject to change that API consumers must ignore.
sub
Identifies the principal that is the subject of the JWT and contains the ID of the Verifalia user (not to be confused with the user name or with the account ID).
exp
Identifies the expiration time on or after which the bearer token will not be accepted for processing; it is serialized as the number of seconds since Epoch.
verifalia:mfa
This custom claim is only returned when the user needs to utilize an additional authentication factor to finalize the authentication process; it includes an array listing the supported authentication factors.
The supported value is totp
, signaling the availability of a Time-Based One-Time Password (TOTP) factor; any other value may change and must be ignored by API consumers.
verifalia:permissions
v2.7+
This custom claim contains all the effective permissions granted to the user for the current session, based on their configuration.
It is structured as an array of strings, where each string represents a permission in the format resource[:operation[:scope]]
.
- If the
scope
block is omitted, the account-wide scope must be assumed when evaluating the permission.
- If the
operation
block is omitted, all operations must be assumed when evaluating the permission.
- The API also supports the
*
wildcard to represent any value within a segment. For example: email-verifications:*:own
means the user is granted all operations on the email-verifications
resource, but only within his or her own scope.
verifalia:user-type
v2.7+
This custom claim identifies the user's type.
The supported values are:
Administrator
- has complete, unrestricted access to the Verifalia account;
Standard
- has flexible, granular permissions;
BrowserApp
- has fixed, non configurable permissions, and is tailored for our embeddable widget and public-facing applications.