CLI Authentication

Connect to your Provisionr workspace to run CLI commands

Activate Your Device

An activation token is used by the CLI client installed on your computer to securely authenticate with the API. The API will return a refresh token that expires after 90 days and is stored securely on your computer so you do not need to save any tokens.

Prerequisite: Please install the CLI client if you have not already.

Workspace UI

1. Sign in to your Workspace UI

   Visit https://wks-{8char}.provisionr.io and sign in.

2. Navigate to CLI page

   In the left global sidebar, click on the user settings icon in the bottom left corner. Locate the API Credentials navigation sidebar section and click the Command Line Interface (CLI) link.

3. Generate an Activation Token

   Click the Create Activation Token button. Copy the prv login ... code block to your clipboard.

   If you already have run the prv login command and only need the activation token, copy the token itself to your clipboard.

4. Redeem your Activation Token

   Open a new window or tab in your preferred Terminal (ex. macOS Terminal, iTerm2, Ghostty, Warp, etc). Paste the prv login ... command and run it.

   Follow the prompts in your terminal to finish activating your device.

   Your device refresh token expires after 90 days. After your token expires, you will need to follow these steps again to obtain a new activation token. If device trust checks fail or your token is revoked, you can use these steps to generate a new activation token.
5. Explore the commands and wizard

   Run the prv command to see a list of example usage.

   prv
   

   See the usage guide for tips on how to use the CLI.

Deauthorize Your Device

For security and system design simplification reasons, only one of your computers can be active at a time (per email address per workspace). You can revoke your credentials and generate a new activation token if your device trust checks no longer pass or you want to activate a different device.

You can revoke your credentials from the CLI using the prv logout command.

You can revoke your credentials from the Web UI from the CLI settings page.

Workspace UI

1. Sign in to your Workspace UI

   Visit https://wks-{8char}.provisionr.io and sign in.

2. Navigate to CLI page

   In the left global sidebar, click on the user settings icon in the bottom left corner. Locate the API Credentials navigation sidebar section and click the Command Line Interface (CLI) link.

3. Revoke the Token

   Click the Revoke Device Token button.

   If you already have run the prv login command and only need the activation token, copy the token itself to your clipboard.

4. Remove the Connection from your CLI Client

   After your token has been revoked in the Web UI, the CLI client can no longer authenticate with the server.

   To cleanup the connection on your computer, run the prv logout command and remove the connection. If you re-authenticate with a new activation token, the old connection with the same domain is replaced.

   prv logout
   
5. Generate a New Activation Token

   If you are ready to activate your device again, follow the Activation Token instructions.

Command Line Interface (CLI)

1. Open your Terminal
2. Run the logout command

   prv logout
   

   Follow the prompts to remove the connection that you want to remove.

   Your credentials will be revoked on the server-side as well if the CLI client is still able to authenticate with the server.

Frequently Asked Questions

Multiple Workspaces

You can connect to multiple workspaces and switch between them easily.

To authenticate to a second or third workspace, simply generate an activation token for that workspace and follow the instructions above.

You can run the prv login command to easily switch between connections.

Standard and Admin Accounts

Your CLI client uses the domain name of your workspace as the unique identifier. We do not support multiple user accounts accessing the same workspace from the user profile on your computer.

The connections are stored in your home folder in ~/.config/provisionr/connections.json and is unique for each user profile using your computer. If you use fast user switching to different user profiles or two different computers, then you could use a different user account to connect to the same workspace.

Debugging Your Connection

If you are experiencing problems are want to see all of the information about Provisionr on your computer, you can use the debug command.

prv debug

Security Architecture

Activation Token Flow

An activation token is valid for 15 minutes after it is generated. If a token expires, the user can simply generate a new token.

Only one device is supported at a time for each user.

A user can generate an activation token as long as they are assigned to a role with the access.cli permission.

Refresh Token Flow

Each refresh token is valid for 90 days. Each access token is valid for 60 minutes. After an access token expires, the refresh token is used for obtaining a new access token.

If a device is deleted in the UI or when running prv logout, the refresh token and access tokens are immediately revoked.

Connection Data

The connection file is saved in ~/.config/provisionr/connections.json.

This is managed by the Provisionr CLI client and is not user editable. Use prv login and prv logout to manage connections.

{
    "access_created_at" => "2025-12-14T04:07:54Z"
    "access_expires_at" => "2025-12-14T05:07:54Z"
    "access_bearer_token" => "prv-<48-char-token>"
    "domain" => "wks-23def456.provisionr.io"
    "exceptions" => true
    "refresh_created_at" => "2025-12-13T13:45:46Z"
    "refresh_expires_at" => "2026-03-13T13:45:46Z"
    "refresh_bearer_token" => "prv-<48-char-token>"
    "token_type" => "cli_refresh"
    "url" => "https://wks-23def456.provisionr.io"
    "user_name" => "Dade Murphy"
    "version" => 1
    "workspace_device_id" => "wsdev_01hq8xyzabc123def456"
    "workspace_id" => "hqwks_01hq8xyzabc123def456"
    "workspace_token_id" => "wstok_01hq8xyzabc123def456"
    "workspace_user_id" => "wsusr_01hq8xyzabc123def456"
}

Device Trust

Each time an access token is requested by a refresh token, the device metadata is sent to the API. With device trust policies configured, this ensures that each device is checked for configuration and version compliance every hour that commands are being run. If device trust policies are violated, the device is deleted and tokens are revoked. The user can generate a new activation token after they meet device trust criteria.

Each activation token is bound to an IP address so you will need to reactivate if your IP address changes. If your IP address changes frequently, consider using your company VPN with a static IP (if available).

In the future, we will support device trust integration with several popular Mobile Device Management (MDM) vendors (Jamf, etc).

Key	Your Machine Data
app_composer_path	/Users/masked/Library/Application Support/Herd/bin//composer
app_composer_version	2.8.9
app_cli_version	1.2.3
app_php_path	/Users/masked/Library/Application Support/Herd/bin//php
app_php_version	8.4.10
ip_address	12.34.56.78
os_chipset	Apple M1 Pro
os_hostname	z3r0c00l-m1
os_platform	macOS
os_serial	XXXXXXXXXX
os_uuid	XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
os_version	15.6.0