Managing API Keys
5 minute read.
TrueNAS 25.04 and later uses a versioned JSON-RPC 2.0 over WebSocket API with support for user-linked API access keys (API Reference).
User-linked API keys allow administrators to configure per-user access to the TrueNAS API. Keys are revocable and can be configured to expire on a preset date.
Click laptop My API Keys on the top right toolbar account_circle user settings dropdown menu to open the User API Keys screen.
The User API Keys screen shows a table listing API keys added to the system, and allows adding, searching for, editing, or deleting keys.
Click API Docs to view API Documentation embedded within the system.
Active Directory/LDAP user-linked API key support is available to TrueNAS Enterprise customers only.
Always back up and secure keys. TrueNAS displays the key string only once, in the API Key confirmation dialog, immediately after creation.
User-linked API keys allow password-equivalent access to the TrueNAS middleware. API keys are not subject to the two-factor authentication (2FA) configuration of the associated user account. A compromised API key results in access to the TrueNAS API as the associated user, even if the account is configured to require 2FA.
For increased security, HTTPS with SSL/TLS transport security is required for TrueNAS API authentication using API keys. TrueNAS automatically revokes any user-linked API keys passed as part of an authentication attempt via insecure (HTTP) transport. A revoked API key cannot be used until it is reset. Resetting generates a new key-string.
Remember to update clients to use the new key.
Open the User API Keys screen by clicking Settings on the top toolbar or API Keys on the Users screen.
Click Add to open the Add API Key screen.
Enter a descriptive name for the key. Select an administrative user to associate with this key from the Username dropdown.
To add a user API key token that does not expire (no expiration date), leave Non-expiring enabled. A non-expiring key remains active until it is manually revoked or changed to expire.
To create a key with a scheduled expiration, disable Non-expiring by clearing the checkbox. Click on the calendar icon in the Expires On field and select the expiration date. The field does not allow typing a date.
Click Save. The API Key dialog opens with a generated key string. TrueNAS API key strings are 64 randomly generated characters long.
The token only shows in the API Key dialog. To save the key for use as an authentication token, click Copy to Clipboard, paste it into a text file, then save the fle in a secure location.
Click Close to return to the User API Keys screen.
Legacy API keys created in TrueNAS 24.10 or earlier migrate to the root, admin, or truenas_admin account, depending on server configuration.
Existing API keys created via the TrueNAS API (not UI or TrueCommand) that specify an allow list with white-listed API methods are revoked upon upgrade because there is no clean way to migrate to the new system. Administrators should create a service account (a user account for this particular purpose), define desired access rights for this service account, generate a new user-linked API key, and distribute it to the API client.
Select the user row and then click edit edit to open the Edit API Key screen.
Make the desired changes and click Save.
To remove the existing API key string and generate a new random key, select Reset. The API Key dialog opens, showing a new key string. Click Copy to Clipboard to copy the token, then paste it into a text file and save it in a secure location.
Update any clients using the reset API Key with the new key string.
Click delete delete for any API key on the list to remove that key. TrueNAS opens a Delete API Key dialog.
Select Confirm, then click Delete.
Click API Docs on the User or User API Keys screen to access the TrueNAS API documentation built into the system. A new browser window opens, showing the API documentation Table of Contents.
Click the link for the content you want to access:
- JSON-RPC 2.0 over WebSocketAPI shows an overview of the JSON-RPC 2.0 format with example objects.
- API Methods shows a table of contents listing TrueNAS API methods
- API Events shows the list of API methods with query call options
- Jobs shows an overview of the job options, uploading/downloading file example scripts, and information on running a query for job status.
- Query Methods shows query basic usage, supported operators, and information on query operations and syntax.
TrueNAS 25.04 and later uses a versioned JSON-RPC 2.0 over WebSocket API. API versions are numbered in conjunction with TrueNAS version releases.
The API documentation provides information about supported API methods and events. Documentation is included for all API versions supported by the current TrueNAS release and defaults to the latest supported API. Use the dropdown to view documentation for different supported API versions.
Advanced users can interact with the TrueNAS API to perform management tasks using the TrueNAS API Client as an alternative to the TrueNAS web UI.
This websocket client provides the command line tool midclt and allows users to communicate with middleware using Python by making API calls.
The client can connect to the local TrueNAS instance or to a specified remote socket.
For more information on the API documentation see API Reference.