Developer Docs
Portal Login Get Started

CLI Provisioning

Provision a new device directly from the developer CLI by using a one-time project group 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 group-specific token together with the device UUID to the Portal.

The Portal validates the token against the target project group and then decides whether the device should be created, re-provisioned inside the same group, or moved from another group of the same company. On success, the endpoint returns the binary license payload as the HTTP response body. License capacity is drawn from the parent project's allocation via ProjectLicenseService.

Group token lifecycle

  • Each project group can have exactly one active CLI provision token.
  • The token is generated from the group 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 group 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 group.
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 group of the same company is moved into the token group before the license is returned.

Provisioning behavior

Device state Result
Device UUID does not exist yet Create the device in the token group and return license.bin.
Device UUID already exists in the same group Re-provision the device and return a new license.bin.
Device UUID exists in another group of the same company and force_move=true Move the device into the token group and return license.bin.
Device UUID exists in another group of the same company and force_move=false Return a conflict response naming the current group.
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"
X-Group-Id: 42
X-Project-Id: 42

X-Group-Id identifies the project group the device was provisioned into. X-Project-Id is retained as a backward-compatible alias with the same numeric group id.

Example with curl

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

Force move from another group of the same company

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

Provisioning sequence

  1. Open the project group 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 group 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 group 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 "Group Name" and Device in use.
422 Validation failed or no active license with an available device slot is currently available for the parent project allocation.
500 The Portal could not build the binary license payload, for example due to missing signing key configuration.

Security notes

  • Treat the group 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.

← Integration Guide Portal API →