TrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.
Managing API Keys
4 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 automatically 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.
This screen displays a list of API keys added to your system and allows you to add, search, edit, or delete keys. Click API Docs to view API Documentation.
Click Add to open the Add API Key screen.
Type a descriptive name for the key. Use the Username dropdown to select an administrative user to associate with this key.
Active Directory/LDAP user-linked API key support is available to TrueNAS Enterprise customers only.
Accept the default Non-expiring to create a token with no expiration date. A non-expiring key remains active until it is manually revoked or updated.
To create a key with a scheduled expiration, click to clear the Non-expiring checkbox. Click on the Expires On field and use the calendar dropdown to select the expiration date.
Click Save to generate the key.
TrueNAS displays an API Key dialog containing the generated key string. TrueNAS API key strings are 64 characters long and randomly generated.
Click Copy to Clipboard and save the API key string in a secure location.
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.
Click Close to return to the User API Keys screen.
Click edit edit for any API key on the list to open the Edit API Key window and modify that key.
Select Reset to remove the existing API key string and generate a new random key. The dialog displays the new key and the Copy to Clipboard option. Click to copy the new API key string then 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 to access the TrueNAS API documentation built into the system.
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.