How to issue a capability token

A capability token is a signed credential that grants a device, service, or session access to a specific platform capability. Tokens are Ed25519-signed, self-describing, and time-bounded. Issuing a token means generating a signed credential using the platform's key material and delivering it to the recipient. This guide covers single-token issuance for a device or service.

For the authorization model that capability tokens operate within, see machine-based-auth. For the full pairing flow that culminates in a token, see pair-a-new-device.

[edit]Prerequisites

• Administrator access to the platform's key issuance service (or the tool-wallet binary if issuing via wallet integration)
• The recipient's public key or verified device identity
• Knowledge of which capability scope is being granted (INPUT, USER, READ, or a named service scope)

[edit]Step 1: Identify the capability scope

Capability tokens carry a scope field that restricts what the holder can do. Before issuing, decide the scope:

Scope	Grants
READ	Read-only access to public-facing data; no ledger writes
USER	Standard session access; can read entity data, submit queries
INPUT	Full operator access; can write to WORM ledger, trigger F12 Input Machine
service:<name>	Named service-to-service scope; restricts the token to a specific service API

Grant the minimum scope that satisfies the use case. Tokens cannot be narrowed after issuance — issue a new token with a narrower scope if the original is too broad.

[edit]Step 2: Obtain the recipient's public key

The recipient generates an Ed25519 keypair on their device and provides the public key. The public key is a 32-byte value, typically encoded as base64 or hex.

For a PPN node, the public key is generated during device initialisation and available via:

service-vm-host --print-pubkey

For an application session, the public key is generated by the platform pairing tool at pairing time and stored in the device's local key store.

[edit]Step 3: Issue the token

Call the token issuance endpoint with the recipient's public key and the intended scope:

curl -X POST http://<issuance-service-host>:<port>/v1/tokens \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_pubkey": "<recipient-base64-pubkey>",
    "scope": "INPUT",
    "expires_in_seconds": 86400
  }'

The service returns a signed token payload. The token is a self-contained JSON structure signed over its fields with the platform's Ed25519 signing key. Copy the full token value — it is not stored server-side after issuance.

[edit]Step 4: Deliver the token to the recipient

Deliver the signed token payload to the recipient through a trusted channel. The recipient loads the token into their device's local key store:

os-console --load-token <token-payload>

Or for a service:

export PLATFORM_TOKEN=<token-payload>

The token is verified at every API call by checking the Ed25519 signature against the platform's published public key.

[edit]Step 5: Verify the token is active

After the recipient loads the token, confirm access by checking the console status bar (scope should show the expected tier) or by querying the token verification endpoint:

curl -X POST http://<issuance-service-host>:<port>/v1/tokens/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "<token-payload>"}'

A valid token returns the scope, expiry, and subject public key. An invalid signature or expired token returns a 401 response with a rejection reason.

[edit]Key takeaways

• Tokens are Ed25519-signed and self-contained — the issuer does not need to store them after delivery
• Grant the minimum scope; tokens cannot be narrowed after issuance
• Token delivery must use a trusted channel — the token itself proves the holder holds the private key, but delivery determines who receives it
• The platform's token verification endpoint can confirm a token's validity without a live session

[edit]See also

• machine-based-auth — the authorization model that capability tokens are part of
• pair-a-new-device — the full device pairing flow that produces a token as its final step
• rotate-keys — how to replace a token and its underlying keypair at expiry or compromise
• crypto-license-sales-architecture — the cryptographic license model used for software distribution tokens
• service-vm-tenant — the tenant proxy service that validates tokens on API calls