Introduction

From Veridu

Basic Concepts

Before starting it is important to define some common terms:

Client Application or website using Veridu's services.
User Application's user or website's visitor interacting with the application/website.
Client Domain The group of users created by a client.

Clients are represented by a unique API Key and an API Secret, both generated at Dashboard.

Users are represented by a unique User ID inside a client domain, in other words, you can represent your users in the way that best suits your application/website.

Both client and user unique IDs can consist of letters from A to Z in both lower and upper case, numbers, underscores and dashes. (A regular expression that validates a unique ID is [a-zA-Z0-9_-]+)

Common Workflow

For unlogged users

  1. Check local cache (such as cookie, session, etc), for session presence
    1. On a cache miss (absence of session)
      1. Create a readonly session
      2. Store session token in local cache
    2. On a cache hit (presence of session)
      1. If session will expire in less than a minute
        1. Extend session lifetime
        2. Update local cache with new expire time
      2. If session already expired, perform the same steps as described in "On a cache miss (absence of session)"
  2. Initialize JavaScript SDK or Widget Library using client unique ID and session token
  3. JavaScript SDK or Widget Library are ready to use


Check the example implementation using PHP (PHP SDK + JavaScript SDK) on GitHub.com

For logged users

  1. Check local cache (such as cookie, session, etc), for session presence
    1. On a cache miss (absence of session)
      1. Create a read/write session
      2. Assign the newly created session to the current logged in user
      3. Store session token in local cache
    2. On a cache hit (presence of session)
      1. If session will expire in less than a minute
        1. Extend session lifetime
        2. Update local cache with new expire time
      2. If session already expired, perform the same steps as described in "On a cache miss (absence of session)"
  2. Initialize JavaScript SDK or Widget Library using client unique ID and session token
  3. JavaScript SDK or Widget Library are ready to use

Check the example implementation using PHP (PHP SDK + JavaScript SDK) on GitHub.com

API Operations

In this section you will find basic information about our API operation and usage, listed bellow:

  1. Session & Information Access
  2. Security
  3. API Responses
  4. Version
  5. Widgets

Session & Information Access

To access any information from the API, the user has to use a valid session (i.e. not expired), issued by the Session Resource.

Sessions are domain specific, which means that a session issued to client A will only give access to user information that belong to A's domain.

During session creation, a readonly or read/write permission can be set and that implies on different behaviors when a user have or have not been assigned to the session at a later point. Access behavior according to session permission and user assignment is described below.

Permission Assigned Access to personal information Access to other users information Can start a verification process
readonly no not applicable scores only not applicable
readonly yes scores and values scores only no
read/write no not applicable scores only not applicable
read/write yes scores and values scores only yes

It is important to note that after a session is assigned to a user, it can't be unassigned or reassigned to another user.

Information related to verification methods is always accessible to assigned/unassigned, readonly or read/write sessions. In other words, user A can always list the verification methods user B has used to verify his profile.

Security

Below are some of the measures currently in use to ensure API access security.

Hypertext Transfer Protocol Secure (aka. HTTPS)

All communication to the API has to be done using HTTPS, otherwise it will return an error API_CHANGE_PROTOCOL error.

HMAC Signatures

Session related and user creation requests have to be signed using a SHA1-based or SHA256-based HMAC signatures, otherwise it will return an REQUEST_SIGNATURE_MISSING error.

The signature is based on a query string (encoded according to RFC1738) that contains the following fields in the following order:

client Client's unique ID (issued by Veridu).
hash Hash algorithm used to sign payload (optional, default: sha1)
method HTTP method used in the request.
nonce An arbitrary string, to identify the request.
resource Full URL to requested resource.
timestamp Number of seconds since epoch (aka. current unixtime).
version API version in use.

To sign a request you will also need the API Secret (issued by Veridu).


Example PHP 5.3+ SHA1 Signature function
  1. //using SHA1
  2. function signRequest($client_id, $method, $resource, $secret, $version) {
  3. 	$param = array(
  4. 		'client' => $client_id,
  5. 		'method' => strtoupper($method),
  6. 		'nonce' => bin2hex(openssl_random_pseudo_bytes(10)),
  7. 		'resource' => $resource,
  8. 		'timestamp' => time(),
  9. 		'version' => $version
  10. 	);
  11. 	ksort($param);
  12. 	$param['signature'] = hash_hmac('sha1', http_build_query($param, '', '&'), $secret);
  13. 	return http_build_query($param, '', '&');
  14. }


Example PHP 5.3+ SHA256 Signature function
  1. //using SHA256
  2. function signRequest($client_id, $method, $resource, $secret, $version) {
  3. 	$param = array(
  4. 		'client' => $client_id,
  5. 		'hash' => 'sha256',
  6. 		'method' => strtoupper($method),
  7. 		'nonce' => bin2hex(openssl_random_pseudo_bytes(10)),
  8. 		'resource' => $resource,
  9. 		'timestamp' => time(),
  10. 		'version' => $version
  11. 	);
  12. 	ksort($param);
  13. 	$param['signature'] = hash_hmac('sha256', http_build_query($param, '', '&'), $secret);
  14. 	return http_build_query($param, '', '&');
  15. }

Signatures must be sent as request payload for POST, PUT and DELETE requests and as query string for GET requests.

ATTENTION Signatures have a lifetime of 1 minute to avoid Replay Attacks.

Session Lifetime

Sessions have a lifetime of 1 hour. A session can have its lifetime extended for a further 1 hour if extended before it expires.

After expired, all requests will return a SESSION_TOKEN_EXPIRED error and a new session has to be created.

See more about sessions in the Session Resource.

API Responses

API responses are all in JSON format and have a boolean status field that describes if the operation was successful or not.

Besides the status item on responses, the HTTP response code is meaningful according to the response.

See more about errors in the Error Listing.

Version

When using any endpoint of Veridu´s API use the following syntax to configure your API endpoint "<url_api>/<version>/<endpoint>". E.g. https://api.veridu.com/0.3/provider

For more information read Version.


Widgets

A Widget Library is available to decrease the time invested in integration and to provide a living example of how to integrate the API's resources to create a custom rich user experience, as it is created using the API resources and calls.

The usage of the Widget Library is highly recommended although is not mandatory.

Check all available widgets here.

Code Samples

Integration code samples can be found at Veridu's sample repository on GitHub.