API_Key

The create command has one required property, name, and one optional property allowlist. See Create Command Properties below for more information on these properties. Enter the command string then press Enter. The command returns the API key when successful.

From the CLI prompt, enter:

auth api_key create name=name

Where name is the name you want to assign to the key.

auth api_key create name=apikey3
API Key: 3-xTqwhyf3SrUgUlotMQEEGuUr6oRvqg89SBDfXob6xtWSgLbRiDBr6SVRWxswSXx3

Enter the create command name property argument followed by the allowlist property argument. You can also specify an HTTP method and a WebSocket API method. Enter the command string then press Enter. The command returns the API key when successful.

From the CLI prompt, enter:

auth api_key create name=name allowlist=[{“method”:"METHOD",“resource”:"api.resource"}]

Where:

• name is the name you want to assign to the key.
• METHOD is the HTTP method you want the key to use. Options are GET, POST, PUT, DELETE, CALL, and SUBSCRIBE.
• api.resource is the WebSocket API resource you want to use. Append “/api/docs/” to the end of your TrueNAS web UI address to see our full list of WebSocket API resources.

auth api_key create name=apikey3 allowlist=[{"method":"SUBSCRIBE","resource":"certificate.query"}]
API Key: 3-xTqwhyf3SrUgUlotMQEEGuUr6oRvqg89SBDfXob6xtWSgLbRiDBr6SVRWxswSXx3

The delete command has one required property, id. Enter the property argument using the = delimiter to separate the property and value. Enter the command then press Enter. The command returns nothing when successful.

From the CLI prompt, enter:

auth api_key delete id=number

Where number is the list number of the API key you want to delete. Use the query command to retrieve id numbers for all API keys on the system.

auth api_key delete id=1

The get_instance command has one required property, id. Enter the property argument using the = delimiter to separate the property and value. Enter the command then press Enter. The command returns a table of properties for the specified API key when successful.

From the CLI prompt, enter:

auth api_key get_instance id=number

Where number is the list number of the API key you want to delete. Use the query command to retrieve id numbers for all API keys on the system.

auth api_key get_instance id=2
+------------+---------------------------+
|         id | 2                         |
|       name | apikey2                   |
| created_at | 2023-08-22T19:58:59+00:00 |
|  allowlist | <list>                    |
+------------+---------------------------+

The query command does not require entering property arguments. Enter the command then press Enter. The command returns a table of properties for all API keys when successful.

From the CLI prompt, enter:

auth api_key query

auth api_key query
+----+---------+---------------------------+-----------+
| id | name    | created_at                | allowlist |
+----+---------+---------------------------+-----------+
| 2  | apikey2 | 2023-08-22T19:58:59+00:00 | <list>    |
| 3  | apikey3 | 2023-08-22T20:14:59+00:00 | <list>    |
| 4  | apikey4 | 2023-08-22T20:17:44+00:00 | <list>    |
+----+---------+---------------------------+-----------+

The update command has one required property, id, and three configurable properties. See Update Command Properties below for details. After specifying the id of the API key you want to update, you must include at least one of the properties. Enter -- after entering the id property argument to open the interactive argument editor. Enter the command string then press Enter. The command returns a table of properties for all API keys when successful.

From the CLI prompt, enter:

auth api_key update id=number name=name allowlist=[{“method”:"METHOD",“resource”:"api.resource"}] reset=true/false

Where

• number is the list number of the API key you want to update. For example, the first API key created on the system would be 1.
• name is the new name you want to assign to the key.
• METHOD is the HTTP method you want the key to use. Options are GET, POST, PUT, DELETE, CALL, and SUBSCRIBE.
• api.resource is the WebSocket API resource you want to use. Append “/api/docs/” to the end of your TrueNAS web UI address to see our full list of WebSocket API resources.
• true/false determines if you want to remove the existing API key and generate a new random key.

auth api_key update id=2 name=apikey3 allowlist=[{"method":"SUBSCRIBE","resource":"certificate.query"}] reset=true