api_key

6 minute read.

Last Modified 2023-11-17 12:56 EST

The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!

api_key commands are based on API key creation and management functions found in the SCALE API and web UI. Use to create new API keys, delete or update existing keys, and locate information on one or all keys added to the system.

Enter auth api_key ls to view the list of available commands.

Commands	Description
`auth api_key create`	Creates an API key.
`auth api_key delete`	Deletes the API key matching the ID entered.
`auth api_key get_instance`	Provides API key information for the ID entered.
`auth api_key query`	Provides information on all API keys configured in the system.
`auth api_key update`	Updates the API key matching the ID entered.

Interactive Argument Editor

Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Click for more information
The interactive argument editor is a text user interface (TUI) that can help enter complex commands with multiple configurable properties. It shows expected properties, defaults, input types (string, boolean, integer, or array), and can include command instructions or warnings.
Optional properties, indicated by the # symbol, are disabled by default. Required properties are enabled. Do not disable properties that are enabled by default.
To configure required properties, enter a space after the colon then add the value.
To enable optional properties, delete # from the corresponding line.
Some required properties are disabled if they are part of a pair of properties where one or the other is required. Select one property to enable and enter a value.
Press F2 or click Save to save the modified file.
Press F10, Esc, or click Quit to exit the TUI. The command automatically executes upon exit.

auth api_key create

The auth api_key create command allows you create simple or complex API keys.

auth api_key create has one required property, name, and one optional property allowlist. See api_key create Properties below for details.

Enter the command string then press Enter. The command returns the API key when successful.

Always back up and secure keys. The key string displays only one time, at creation!

api_key create Properties

Property	Required	Description	Syntax Example
`name`	Yes	Enter a user-readable name for the API key using alphanumeric characters with or without the underscore `_`. Enter the property argument using the `=` to separate property and value. Double-quote values with spaces or special characters.	`name=mykey`
`allowlist`	No	Use to enter the HTTP method and WebSocket API authorized to use the API key. Enter the required `resource` permitted to use this key. Append /api/docs/ to the end of your TrueNAS web UI address to see our full list of WebSocket API resources. Enter the HTTP `method` as a string using any of these values: `GET`to retrieve information about the API resource. `POST` to create an API resource. `PUT` to update an API resource. `DELETE` to delete the API resource. `CALL`,or `SUBSCRIBE` Enclose property arguments inside the curly brackets `{}` within square brackets `[]`. Enter property aguments using the `=` to separate double-quoted property and values. Separate each propery argument with a comma and space.	`allowlist=[{“method”="SUBSCRIBE", [“resource”="certificate.query"}]`

Command Example

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

Complex api_key Command Example

Enter the auth api_key create command with the name and allowlist property arguments. Optionally, include an HTTP method (GET, POST, PUT, DELETE, CALL, or SUBSCRIBE) and a WebSocket API method by appending /api/docs/ to the end of your TrueNAS web UI address to see our full list of WebSocket API resources.

Enter the command string then press Enter. The command returns the API key when successful.

Command Example

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

auth api_key delete

The auth api_key delete command deletes the API key matching the key ID entered.

Use the auth api_key query command to obtain a list of ID numbers for API keys on the system and again after deleting an API key to verify it is removed.

auth api_key delete has one required property, id. id is the system-assigned ID number for the API key found in the auth api_key query command output.

Enter the property argument using the = delimiter to separate the property and value. Enter the command string then press Enter. The command returns nothing when successful.

Command Example

auth api_key delete id=1

auth api_key get_instance

The auth api_key get_instance command returns API key properties for the specified ID.

auth api_key get_instance has one required property, id. id is the system-assigned ID number for the API key found in the auth api_key query command output.

Enter the property argument using the = delimiter to separate the property and value. Enter the command then press Enter. The command returns a table with the ID, name, creation date and time, and an allow list for the specified API key.

Command Example

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

auth api_key query

The auth api_key query command returns a table of properties for all API keys.

Use to locate the system-assigned ID number required in the auth api_key delete, auth api_key get_instance and auth api_key update commands.

auth api_key query does not require entering property arguments. Enter the command then press Enter. The command returns a table with the ID, name, creation date and time, and an allow list for all API keys.

Command Example

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>    |
+----+---------+---------------------------+-----------+

auth api_key update

The auth api_key update command allows you to change or reset existing API keys.

Use the auth api_key query command to obtain API key ID numbers, and after making changes to verify the changes are applied.

auth api_key update has one required property, id, and three configurable properties. Enter the id of the API key, then include at least one of the properties. See api_key update Properties below for details.

Enter the command string then press Enter. Or enter -- after id to open the interactive argument editor. The command returns an empty line.

api_key update Properties

Property	Description	Syntax Example
`name`	Enter a user-readable name for the API key using alphanumeric characters with or without the underscore `_`. Enter the property argument using the `=` to separate property and value. Double-quote values with spaces or special characters.	`name=mykey`
`allowlist`	Use to enter the HTTP method and WebSocket API authorized to use the API key. Enter the required `resource` permitted to use this key. Append /api/docs/ to the end of your TrueNAS web UI address to see our full list of WebSocket API resources. Enter the HTTP `method` as a string using any of these values: `GET`to retrieve information about the API resource. `POST` to create an API resource. `PUT` to update an API resource. `DELETE` to delete the API resource. `CALL`,or `SUBSCRIBE` Enclose property arguments inside the curly brackets `{}` within square brackets `[]`. Enter property aguments using the `=` to separate double-quoted property and values. Separate each propery argument with a comma and space.	`allowlist=[{“method”="SUBSCRIBE", [“resource”="certificate.query"}]`
`reset`	Enter `true` to remove the existing key and generate a new one.	`reset=true` or `reset=false`

Command Example

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

api_key

auth api_key create

api_key create Properties

auth api_key delete

auth api_key get_instance

auth api_key query

auth api_key update

api_key update Properties

Related Content

SCALE CLI Reference

SCALE Tutorials

SCALE UI Reference

Have more Questions?