A Fleet API key lets you talk to your Fleet instance directly. Use one to run scripts, pull device data or connect Fleet to other tools.

Feature/Functionality

Overview

Fleet (FleetDM) API keys authenticate requests sent straight to your Fleet instance. You can create them in three ways:

• From Factorial IT, as a read-only key.
• From the Fleet dashboard, as a token tied to your Fleet user account.
• From the command line, with the Fleet CLI or the Fleet API.

Fleet API tokens never expire on their own.

How to use: create a key from Factorial IT

1. Go to Settings > Developers and scroll down to the FleetDM API key section.
2. Type a Key name, for example the tool that will use the key.
3. Click Generate key.
4. Copy the token shown in the FleetDM API key created window. It stays available afterwards in the keys table.

Keys created from Factorial IT are read-only. They can see every device and its data, but they cannot change settings or run device actions. They suit external integrations that only need to read your Fleet instance.

To revoke one, open the ⋯ menu on its row in the FleetDM API key table and click Revoke. Any integration using it stops working at once.

Keep the token secret. Whoever has it can read your device inventory.

Create a key from the Fleet dashboard

1. Open your Fleet dashboard from the console via Settings > MDM > Open Fleet.
2. Click your avatar in the top right corner and select My account.
3. Scroll down to API token.
4. Click Get API token.
5. Copy the token. It belongs to your Fleet user account.

This token carries the same permissions as your Fleet user account. Keep it secret.

Create a key from the command line

With the Fleet CLI:

fleetctl login --email your-email@example.com --url https://<your-fleet-instance>
fleetctl get api-token

Or straight through the Fleet API:

curl -X POST https://<your-fleet-instance>/api/v1/fleet/users/<user-id>/api_token \
  -H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
  -H "Content-Type: application/json"

Use the key

Send the token in the Authorization header:

curl https://<your-fleet-instance>/api/v1/fleet/hosts \
  -H "Authorization: Bearer YOUR_FLEET_API_TOKEN"

Regenerate or revoke a token

• Key created from Factorial IT: go to Settings > Developers > FleetDM API key, open the ⋯ menu on its row and click Revoke.
• Token tied to your Fleet user account: in Fleet, go to My account and click Regenerate API token. The old token stops working straight away.

Troubleshooting and FAQ

Troubleshooting

• An integration stopped working. Its key may have been revoked, or the user token regenerated. Create a new key and update the integration.
• A request to change settings or run an action fails. Keys created from Factorial IT are read-only. Use a token tied to a Fleet user account with the right permissions.
• You lost the token. For a key created from Factorial IT, find it again in the keys table. For a user token, regenerate it in My account in Fleet.

FAQ

1. Do Fleet API tokens expire?
   No. They stay valid until you revoke or regenerate them.
    
2. What can a key created from Factorial IT do?
   Read every device and its data. It cannot change settings or run device actions.
    
3. What permissions does a token from the Fleet dashboard have?
   The same as your Fleet user account.
    
4. What happens when I revoke a key?
   Every integration using it stops working at once.