Skip to content

Authorization

In this article, we describe the authorization methods supported by the Regula IDV Platform and explain their use cases.

IDV supports several authorization types that can be passed via the Authorization header or through a queryString parameter. We recommend using the Authorization header as it is a more secure method.

Passing credentials via queryString is allowed only when there is a need to share a URL containing all authentication parameters.

Basic

Basic is a standard authentication method using a username and password, sent in the header along with the keyword Basic, for example:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Login/password authentication is the simplest way to identify a user. In this case, the user is granted all permissions associated with their account.

Bearer

Bearer is token-based authentication. The token is typically issued by the platform as a result of an OAuth2 or SAML authentication process via a third-party identity provider (IdP).

The token is passed in the Authorization header using the keyword Bearer, for example:

Authorization: Bearer <token>

This method is primarily used in the Client Portal. For setting up OAuth2 or SAML, see the IDV Configuration documentation.

Short Token

Short Token (Token or DeepLink QR) is a one-time short-lived token generated by the platform. It is used for quick and secure Device pairing, for example:

Authorization: Token <short-token>
A token can be requested via:

curl -X GET 'https://nightly-idv.regula.app/api/deeplink/qrcode?workflowId=<workflowId>' \
--header 'Authorization: Basic <token>'

A Short Token can be used for the following cases:

  • QR code: a one-time, short-lived QR code generated by the Platform. It can be scanned by a Device to join a Session.

  • Token: used only for initial Device connection.

Connection

Connection is an authorization type designed specifically for Devices. Each Device that interacts with the IDV Platform must be identified and establish a connection. Several methods are supported:

  • Basic — using login and password
  • Short Token
  • API Key
  • Operator registration — registered manually by a Platform operator
  • Auto-registration — device registers itself on the Platform

Any Device that sends or receives Session data must be authorized using a connection type.

To establish a Connection, a Device must provide a minimum set of information:

Parameter Description
deviceId Unique identifier of the Device. Can be a serial number or any unique value.
workflowId Workflow ID the Device will use. A new connection is required if the Workflow changes.
serial (optional) Serial number of the Device.
macAddress (optional) MAC address of the Device.
deviceType (optional) Type of the Device.
heartbeatCadence (optional) Frequency (in seconds) of heartbeat messages.

Example request:

curl --location 'https://dev-idv.regulaforensics.com/api/device/connection' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <token>' \
--data '{
  "deviceId": "NEW_TEST_DEVICE_0111",
  "serial": "1111111222211",  
  "macAddress": "00:00:00:00:00:00",
  "deviceType": "TEST",
  "heartbeatCadence": 2,  
  "workflowId": "fd3ac322-8c92-4236-89a6-b69588b38ac2"
}'

The IDV Platform will respond with a Connection token:

Authorization: Connection <token>

The Connection authorization offers the following benefits:

  • High performance — the token contains all required data, so permission checks don’t need additional DB queries.
  • WebSocket support — connected Devices can subscribe to the ws/device channel and receive Session-related notifications.

API Key

IDV also supports API Key authentication, which is conceptually similar to token-based authorization and is intended for machine-to-machine communication.

For example:

Authorization: ApiKey <Api-key-token>

You can create a key via the CLI idv apikey create command or via a POST request to /api/security/apikeys.

Via CLI

The command supports the following arguments:

Parameter Description
name Human-readable name for the key.
permissions Permissions string in comma-separated format.
expires (optional) Time-to-live in seconds. If omitted, the key does not expire. 
idv apikey create --name "My API key" --expires 6000 --permissions "ephemeral_device:write,person:write"

Via API

The request body supports the following parameters:

Parameter Description
name Human-readable name for the key.
permissions Array of permissions granted to the key.
ttl (optional) Time-to-live in seconds. If omitted, the key does not expire.

Example request:

curl --location 'http://dev-idv.regulaforensics.com/api/apikey' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Token <token>' \
  --data '{
    "name": "My API key",
    "ttl": 6000,
    "permissions": ["ephemeral_device:write"]
  }'

The response will contain the newly generated token, which you can then pass in the Authorization header as follows Authorization: ApiKey <token>.

Example response:

{
  "id": "68cd5cfe1541616e810b1c14",
  "token": "27uu7c_wunykxcvqbj3tvrm_l6fm-crxa5mm3nkoeea2q-dhbcpynbqge5mx0b7i",
  "name": "My API key",
  "permissions": [
    "ephemeral_device:write"
  ],
  "expiresAt": "2025-09-19T15:19:10.032Z"
}