New-ZrToken
Issues a signed, self-contained bearer token for a subject, optionally embedding a role granted at a scope and bounding the token's lifetime.
Syntax
New-ZrToken
-Subject <string>
[-Role <string>]
[-Scope <string>]
[-Type <string>]
[-LifetimeMinutes <int>]
[-Managers <string[]>] [-Port <int>] [-Token <string>] [-TimeoutSec <int>]
Description
New-ZrToken issues a self-contained token for the given subject from the first available manager. When -Role is supplied it embeds that role — optionally scoped with -Scope — into the token, following the RBAC model; when -Scope is omitted the role applies at the root scope. Use it to hand an application or user a credential without creating a persistent identity (contrast with a service account, which is a durable identity). The issued token is printed once, so capture it. Requires an active workspace or an explicit -Managers list and an admin token.
The issued token is a live credential printed once. Copy it directly from the console into your application's secret store — never paste a real token into a script, ticket, or chat. The example below uses a placeholder value; a real token is a long opaque string.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
-Subject | string | Yes | The subject (identity) the issued token represents. Position 0. |
-Role | string | No | An optional role to embed in the token. |
-Scope | string | No | The scope at which the embedded role applies (for example zaris:store:orders). Defaults to the root scope when omitted. |
-Type | string | No | An optional token type that categorizes the issued token. |
-LifetimeMinutes | int | No | The lifetime of the token in minutes. When omitted, the server default applies. |
-Managers | string[] | No | Management Service endpoints (host, host:port, or URL) to target. When omitted, the active workspace's managers are used. |
-Port | int | No | Management Service port for bare-host managers. Default 7801. |
-Token | string | No | Admin bearer token for authenticated control-plane calls. |
-TimeoutSec | int | No | Per-request timeout in seconds. Default 30. |
Examples
Issue a 60-minute token for app1 carrying the DataWriter role on the orders store.
New-ZrToken -Subject app1 -Role DataWriter -Scope zaris:store:orders -LifetimeMinutes 60
The token is printed once; capture it into a secret store (shown here as a placeholder):
Token for app1 (jti a1b2c3d4):
<TOKEN-VALUE-SHOWN-ONCE>