API Keys
Managing Machine Users and API Keys#
Machine users are service accounts that allow applications or services to interact with the API on behalf of an organization. This documentation outlines how to create, manage, and generate API keys for machine users.
Creating a Machine User#
To create a new machine user, use the hf users create-machine command followed by the name of your desired machine user identifier.
This command will generate a machine user ID. Newly created machine users are initially disabled by default and must be granted permissions before they can interact with the API.
Listing Users#
To view all users, including machine users, use the hf users list command:
The output shows both human and machine users, along with their status and permission levels.
Enabling a Machine User#
Once created, you will need to enable the machine user to allow it to interact with the system. Use the appropriate command to update the machine user's status from LEVEL_DENY to an appropriate permission level. You may also edit the user's permission levels in the product's user interface.
Creating an API Key for a Machine User#
To generate an API key for a machine user, use the hf users create-key command, specifying the machine user ID and a name for the key.
The command will output a newly generated API key. Make sure to store this key securely, as it is used to authenticate API requests.
You can also specify an expiration duration for the key using the --duration option (e.g., 24h, 7d, 1y). By default, the key does not expire.
Listing API Keys#
To list all API keys associated with a machine user, use the list-keys command:
This command displays the keys, including their names, expiration status, and last usage information.
Disabling or Deleting a Machine User or API Key#
If a machine user or its associated API key is no longer needed, ensure it is disabled or deleted to prevent unauthorized access.