tiCrypt

API Keys

Prerequisites

User Role:

Super-admin

An API key is a secret token that lets a script or another system call the tiCrypt REST API without a user session. Each key has a token type that limits which routes it can reach, an access level, and an expiration date that cannot be changed later. An API key is not a user account: it acts for the Super-admin who created it, within the limits of its type and access level.

note

API keys are used to authenticate programmatic access to tiCrypt. For available endpoints, request formats, and usage examples, see the REST API Reference.

Create a New API Key

Location: Management > Miscellaneous > API Keys

1. Click the Create new API key button in the top right panel.
2. In the Create new API key pop-up, fill in the fields described in the table below.
3. Click Create.
4. In the API key created pop-up, click the Copy button. tiCrypt shows "API key copied".
5. Paste the API key where necessary.
6. Click Close. Close stays disabled until you copy the key.

The following table describes the fields of the Create new API key pop-up.

Field	Description
Type	The routes the key can reach: Drive, Multi, Project, Team, User or VM. You select one type. The default is VM. Multi appears only when the backend supports multi-type keys.
Capabilities	Shown only for Multi. The types the key can reach: any of Team, VM, Project, Drive and User. Select at least one ("At least one type must be selected").
Access Level	Full control (the default) or Read-only.
Expiration	Required. The earliest date is tomorrow. The hint reads "You cannot renew this later."
Description (optional)	A note on what the key is for, up to 250 characters, without <, >, { or }. Markdown is supported.

Result: The key appears in the API Keys table. The key value itself is shown only in the API key created pop-up.

caution

The key value is shown once, at creation. It is never stored by the server. If you lose it, delete the key and create a new one. Clicking outside the pop-up does not close it.

Key Types

The key type determines which routes the key can reach. A request outside the key's types is rejected.

Key Type	Grants access to
Drive	Drive routes
VM	VM, image, hardware-setup, realm, and external-server routes
Team	Team, team-quota, and team-usage routes
Project	Project, project-membership, project-usage, and security routes
User	User, profile, certification, managed-object, and permission routes
Multi	The routes of every type selected under Capabilities

Choose the narrowest type that covers the job.

Multi Keys (as of ver. 3.14.1)

Before 3.14.1 a key carried exactly one type, so work spanning resource types needed one key per type, each with its own expiration and rotation.

As of 3.14.1 you can choose the Multi type and select any combination of types under Capabilities. Select all five and one key reaches every route in the REST API, which is what the System Snapshot script expects.

Existing single-type keys are unaffected and keep working after the upgrade.

Read-Only Keys

A key can be set to Read-only under Access Level at creation. Read-only keys are restricted to read and list operations; any request that changes state is rejected. Use a read-only key whenever it is used for reporting, inventory, or monitoring.

A Multi key with every capability selected reaches the whole system, so pair it with Read-only unless the job genuinely needs to write.

The API Keys Table

The following table describes the columns of the API Keys table. Rows of expired keys are shown in red.

Column	Description
Token type	The key's type.
Owner	The Super-admin who created the key.
Read Only	Full control or Read-only.
Created	When the key was created.
Expires	When the key stops working.
Last Used	When a request last used the key.

View an API Key

Location: Management > Miscellaneous > API Keys

1. Select the API key to view.
2. Click the View button in the top right panel.
3. In the detail pane, review the key's details described in the table below.

The following table describes the detail pane of an API key. The header shows "<type> API key" and how long until the key expires, or how long ago it expired.

Item	Description
Description	The key's description, if it has one.
Owner	The Super-admin who created the key. Click it to open the user.
Created on	When the key was created.
Expires on or Expired on	The expiration date.
Last used on	When a request last used the key, or "Never used".
Access level	Full control or Read-only.
Capabilities	Shown only for Multi keys: the types the key can reach.
ID	The key's identifier, not the key value.

Result: The detail pane shows the key's settings. The key value is never shown again.

Refresh the API Key List

Location: Management > Miscellaneous > API Keys

1. Click the Refresh button in the top right panel.

Delete API Key(s)

bulk-action

Location: Management > Miscellaneous > API Keys

1. Select the API key(s) to delete.
2. Click the Delete button in the top right panel.
3. In the Delete API key(s)? prompt, which reads "Deleting an API key is permanent.", click Delete.

Result: The keys are removed, and any request that uses them is rejected.

Deleting an API key cannot be undone

Deleting an API key is a permanent action and cannot be undone.

Related

• REST API Reference: the routes each key type reaches and how to pass a key with a request.
• System Snapshot: a read-only inventory of the whole system made with one Multi key.