Token Installation and Management

Create, install, and manage DeGirum Workspace tokens for PySDK, including the one-token-per-device rule, auto-renewal behavior, and secure practices for small setups and large fleets.

This guide explains how to create, install, and manage DeGirum Workspace tokens for PySDK deployments, from a handful of developer machines to large fleets. It also clarifies key operational behaviors such as auto-renewal and the single-token-per-device rule, which affect best practices.

What a Workspace token is used for

A Workspace token represents your Workspace permissions and is required for PySDK operation. It is used for:

• AI Hub access and inference: Authenticates and authorizes actions based on Workspace permissions (e.g., cloud inference and access to Workspace resources).

• PySDK license generation: PySDK uses the token to obtain the license required to run.

• Application package licenses: The token is also used to generate and validate licenses for DeGirum application packages such as degirum-face and degirum-speech.

For PySDK deployments, install a Workspace token, not a personal token. A personal token cannot generate PySDK licenses or application package licenses.

Workspace plans and permissions matter

Each Workspace is on a specific plan (see Workspace Plans for details), and the token’s capabilities depend on:

• the Workspace’s plan and entitlements, and

• the permissions granted to that Workspace.

Install a token from the Workspace that has the permissions and plan needed for the workloads you intend to run.

Only one token can be installed on a device.

A device can have only one Workspace token installed at a time (per user environment). This is important when:

• you belong to multiple Workspaces, or

• you switch between Workspaces with different permissions.

Before installing a token, confirm you are using the token for the correct Workspace (the one with the permissions and plan you need). If you install a token for a different Workspace later, it replaces the previous token on that device.

Use device-scoped tokens

DeGirum recommends using one token per device (or per user plus device) because it provides a strong balance of security, traceability, and operational control, especially at scale.

Auto-renewal: security and leak detection

Workspace tokens are often time-limited. Once a token is installed on a device, PySDK can auto-renew it as needed to keep the system running.

If a token is copied off a device and used elsewhere:

• The other party may be able to use and renew that token.

• In practice, renewal becomes an early warning system. If someone else renews the token, your device’s next renewal attempt may fail, alerting you to a potential leak or misuse.

Because tokens are time-limited, leakage is naturally bounded unless the token continues to be renewed.

Auto-renewal can make token misuse more detectable, and device-scoped tokens help keep the blast radius small.

Token security best practices

• Use one token per device (or per user plus device).

• Install tokens once on each device and let PySDK handle renewal.

• Set expirations and rotate tokens as part of lifecycle operations.

• Do not hardcode tokens in code or commit them to repos.

Never-expiring tokens (discouraged)

AI Hub can generate never-expiring tokens, and technically they can be shared. However, DeGirum strongly discourages using never-expiring shared tokens, especially across multiple devices, because:

• they increase the blast radius of a leak,

• they reduce traceability (it is harder to know which device used it),

• they make incident response disruptive (one revoke can break many systems at once).

Use never-expiring tokens only when you have a strong reason and compensating controls (e.g., strict secrets management, tight network controls, and a clear rotation and revocation plan).

Deployment paths

1 to 10 devices: AI Hub UI to install via CLI

This is best for individuals, small teams, and labs.

1

Create a token in AI Hub (UI)

1. Open AI Hub → Workspace → Workspace Tokens

2. Click Generate Token

3. Set:

   • Description (e.g., John-MacBook, Lab-Workstation-01)

   • Expiration (recommended)

4. Copy the token and store it securely

Use descriptions that identify the owner and device. This makes audits and cleanup simpler later.

2

Install the token on the device

On the target device:

degirum token install <YOUR_TOKEN>

Optional verification:

degirum token status

Only one token can be installed on a device. Installing a new Workspace token replaces the existing one.

3

Use PySDK without embedding tokens

Once installed, your applications should typically rely on the installed token so you do not have to pass token=... through scripts and configs.

Pros

• Fast onboarding

• Easy troubleshooting (degirum token status)

• Keeps secrets out of code

Cons

• Requires copy and paste for initial setup

• If you switch Workspaces often, you will need to reinstall the correct token (because only one can be installed at a time)

• Rotation requires re-install on affected machines

10 to 10,000+ devices: fleet provisioning and lifecycle management

This is best for fleets, production rollouts, and customer deployments.

At scale, the goal is:

• zero copy and paste

• one token per device

• central governance

• safe rotation and revocation

Option 1 (recommended): provisioning-time install (IT-managed fleets)

1

Define a token naming convention

In AI Hub, generate tokens using a consistent description scheme, for example:

• team-env-assetid → vision-prod-LAP1234

• customer-site-deviceid → acme-warehouse-GW-008

2

Distribute tokens securely

DeGirum recommends using your existing secure delivery channels:

• MDM (Intune, Jamf)

• provisioning scripts (Ansible, Salt, cloud-init)

• secrets managers (Vault, AWS Secrets Manager, Azure Key Vault)

• manufacturing or staging pipelines

Avoid email, shared documents, and embedding tokens in images or repos.

3

Install during provisioning

On each device:

degirum token install <DEVICE_SPECIFIC_TOKEN>

Optional validation:

degirum token status

4

Lifecycle management (rotate and revoke)

• Lost or decommissioned device: revoke or delete the token in AI Hub

• Reprovision device: issue a new token and reinstall

• Optional local cleanup if the device is reachable:

degirum token clear

Pros

• Fully automatable

• Best auditability and smallest blast radius

• Operationally clean rotation and revocation

Cons

• Requires integrating token distribution into your provisioning workflow

• Rotation is best handled with automation (recommended at scale)

Option 2: self-service enrollment (developer-managed fleets)

If devices are developer-managed, self-service often gives the best user experience:

degirum token create

The CLI guides the user through authentication and installs the token locally. This avoids IT distributing secrets.

Pros

• Best end-user experience

• Minimal secret handling by IT

• Great for onboarding many developers quickly

Cons

• Not ideal for locked-down production devices

• Requires user action during setup

• Users must ensure they enroll into the correct Workspace (only one token can be installed at a time)

Recommended and discouraged practices

Recommended

• One token per device (or per user plus device)

• Install via CLI and keep tokens out of code and config

• Use expirations and rotate as policy requires

• Use descriptive names for traceability

• Ensure the installed token corresponds to the Workspace with the right plan and permissions (since only one token can be installed)

Discouraged

• A single never-expiring token shared across many devices

• Tokens embedded in repos, container images, or plaintext shared documents

Troubleshooting

“License/token missing” or “renewal failed”

1

Check if a token is installed

degirum token status

Confirm you installed a Workspace token (not a personal token). Personal tokens cannot generate PySDK or application package licenses.

2

If missing (or wrong Workspace), install the correct token

degirum token install --token <TOKEN>

3

If renewal fails unexpectedly

Confirm the token hasn’t expired or been revoked in AI Hub.

If you suspect compromise, revoke the token in AI Hub and issue a new one.

FAQ

Why can’t I keep tokens for multiple Workspaces installed at once?

PySDK uses a single installed token for licensing and Workspace permissions in that user environment. If you need to switch Workspaces, install the token for the Workspace you want to use on that device.

Which packages use token-based licensing?

PySDK uses Workspace tokens for licensing, and DeGirum Application Packages such as degirum-face and degirum-speech also rely on token-based license generation and validation.