CLI Provisioning

Provision a new device directly from the developer CLI by using a one-time project token and downloading the resulting license.bin.

---

Overview

The CLI provisioning flow is intended for developer workstations and lab devices. Instead of scanning a QR code and manually creating a device entry first, the CLI sends a project-specific token together with the device UUID to the Portal.

The Portal validates the token and then decides whether the device should be created, re-provisioned inside the same project, or moved from another project of the same company. On success, the endpoint returns the binary license payload as the HTTP response body.

Project token lifecycle

• Each project can have exactly one active CLI provision token.
• The token is generated from the project detail page in the Portal.
• The full token value is shown only once when it is created or rotated.
• The token can be revoked manually from the same project page.
• After revocation, the old token is no longer accepted by the API.

API endpoint

POST /api/projects/provision

Form fields

Field	Required	Description
token	Yes	The active CLI provision token generated for the target project.
device_uuid	Yes	The hardware identifier of the device. Hex strings and UUID-style values are accepted.
device_name	No	Optional display name stored in the Portal for a newly created device. If omitted, the device UUID is used as the device name.
force_move	No	Boolean flag. Accepted values are true, false, 1, 0, "1", and "0". If enabled, a device that already belongs to another project of the same company is moved into the token project before the license is returned.

Provisioning behavior

Device state	Result
Device UUID does not exist yet	Create the device in the token project and return license.bin.
Device UUID already exists in the same project	Re-provision the device and return a new license.bin.
Device UUID exists in another project of the same company and force_move=true	Move the device into the token project and return license.bin.
Device UUID exists in another project of the same company and force_move=false	Return a conflict response naming the current project.
Device UUID belongs to a different company	Return a conflict response because the device is already in use.

Response

On success, the endpoint returns the binary license file directly with Content-Type: application/octet-stream. Save the response body as license.bin and deploy it to the device boot medium as usual.

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="license_2E1E0E1600181207.bin"

Example with curl

curl -X POST https://portal.graphlab.net/api/projects/provision \
  -d "token=PASTE_PROJECT_TOKEN_HERE" \
  -d "device_uuid=2E1E0E1600181207" \
  -d "device_name=Dev Kit 01" \
  --output license.bin

Force move from another project of the same company

curl -X POST https://portal.graphlab.net/api/projects/provision \
  -d "token=PASTE_PROJECT_TOKEN_HERE" \
  -d "device_uuid=2E1E0E1600181207" \
  -d "force_move=1" \
  --output license.bin

Provisioning sequence

1. Open the project in the Portal and generate or rotate the CLI provision token.
2. Copy the token immediately and store it securely on the developer workstation.
3. Read the device UUID from the target hardware.
4. Call POST /api/projects/provision from the CLI, optionally setting force_move=1 when the device should be reassigned from another project of the same company.
5. Store the downloaded payload as license.bin.
6. Deploy the license file to the device and reboot if required.

Error cases

Status	Meaning
404	The token is invalid or has already been revoked.
409	The device already exists in another project of the same company and force_move was not enabled, or the device belongs to another company. Example responses are Device is already in group "Project Name" and Device in use.
422	Validation failed or no active license with an available device slot is currently available for the project company.
500	The Portal could not build the binary license payload, for example due to missing signing key configuration.

Security notes

• Treat the project token like a temporary secret for developer tooling.
• Do not commit the token into source control or ship it in firmware images.
• Rotate the token whenever it has been shared too broadly or copied into insecure logs.
• Use revoke immediately if a token is no longer needed.

For the manual QR-based device onboarding flow, see Licensing & Evaluation.