API Keys

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

You can create an API key in the following ways:

• Via Platform portal UI.
• Via the CLI idv apikey create command.
• Via a POST request to /api/security/apikey.

Via Platform Portal UI

1. On the Platform portal, go to Settings, expand Integrations, navigate to API Keys, and click + Add new API Key:

2. Enter the Name and TTL (Time to Live) values and click the Add permission button:

3. Configure the Scope and Operations values, for example:

• In the Scope field, select Ephemeral Devices.
• In the Operations field, select Write.

The values above are used as an example in this configuration step. Select the appropriate Scope and Operations that meet your specific requirements.

4. Click Save.

5. Now you can copy your API key from the pop-up window:

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 '<base_url>/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"
}