API Keys

IDV Platform supports API Key authentication for machine-to-machine communication.

Each API key has its own permissions that define which Platform resources the application can access and which operations it can perform.

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/apikey.

Via Platform Portal UI

Before you start

API keys are managed by Platform Administrators and other authorized users with the required permissions.

IDV Platform provides built-in roles that allow users to manage API keys:

Admin—provides administrative access to Platform resources, including API keys.
Tech Admin—provides access to technical administration functions, including API key management.

The following permissions control access to API key management:

Permission	Description
`apikey:create`	Create API keys.
`apikey:list`	View the list of API keys.
`apikey:read`	View API key details.
`apikey:update`	Update existing API keys.
`apikey:delete`	Delete API keys.

Create API key

To create an API key:

In the left sidebar, navigate to Settings, click Integrations, and select API Keys.
Click + Add new API Key.
In the Add API Key dialog, enter the following information:
- Name—enter a name to identify the API key.
- TTL (Time to Live)—select how long the API key remains valid from the dropdown list.
In the Permissions section, click Add permission to add a permission row. Define which Platform resources the API key can access and which operations it can perform:
- Scope—select the Platform resource to which the permission applies.
- Operations—select one or more allowed operations.
- Entities—select specific entities where supported, or keep All (*) to apply the selected operations to all entities within the scope.
Entity-level access is supported only for certain scopes and operations. For details and restrictions, see Configure Role Permissions.
- Add additional permission rows as needed.
- Review the configuration and click Save.
- Copy the generated API key from the pop-up window.

Consider the following rules and restrictions:

You can configure only scopes, operations, and entities that do not exceed your own permissions.
Each scope–operation combination can appear only once.
The same scope can appear in multiple permission rows with different operations.
List, Create, and Assign operations require All (*) in the Entities field.
Specific entity IDs can be selected only for scopes and operations that support entity-level restrictions. Refer to Configure Role Permissions as there are some specific entity restrictions.
If List and Read require different entity selections, configure them in separate permission rows.
At least one complete permission row must remain.
Assign only the permissions required for the intended integration.

For more information about the permission model, see Role-Based Access Control.

View and edit API keys

Users with the required permissions can view and modify existing API keys:

apikey:list—view the list of API keys.
apikey:read—view API key details.
apikey:update—modify an existing API key.

For more details refer to Permissions.

To view or edit an API key:

Navigate to Settings, click Integrations, and select API Keys.
Find the API key in the table and click its row.
In the dialog, view or modify the following fields which Platform resources the API key can access and which operations it can perform:
Name—the name used to identify the API key.
Expires At—the date and time when the API key expires.
Permissions—the scopes, operations, and entities the API key can access. Refer to Configure Role Permissions for more instructions.
Review the changes and click Save.

You can configure only scopes, operations, and entities that do not exceed own permissions.

Delete API key

Users with the apikey:delete permission can delete API keys that are no longer needed. For more details refer to Permissions.

To delete an API key:

Navigate to Settings, click Integrations, and select API Keys.
Find the API key you want to delete.
In the last column of the corresponding row, click the ... menu.
Select Delete.

Deleting an API key removes its access to IDV Platform. Applications using the deleted key can no longer authenticate with it.

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"

You can configure only scopes, operations, and entities that do not exceed your own permissions.

Via API

You can create an API key by sending a POST request to /api/apikey.

You can configure only scopes, operations, and entities that do not exceed your own permissions.

The request body supports the following parameters:

Parameter	Description
`name`	Human-readable name for the key.
`permissions`	Array of permissions granted to the key. Each permission follows the `scope:operation:entities` format.
`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": [
      "workflow:list:*",
      "workflow:read:*"
    ]
  }'

The response contains the newly generated token, which you can pass in the Authorization header as follows:

Authorization: ApiKey <token>

Example response:

{
  "id": "68cd5cfe1541616e810b1c14",
  "token": "<generated_api_key>",
  "name": "My API key",
  "permissions": [
    "workflow:list:*",
    "workflow:read:*"
  ],
  "expiresAt": "2025-09-19T15:19:10.032Z"
}

For the complete list of API key management endpoints, supported operations, request parameters, and response schemas, see the IDV Platform API documentation (Swagger).