`tenant` command group¶

Q: Do I need to log in before running tenant commands?

Yes. Every tenant command is a remote gRPC call. Create a host profile with profile hosts create, then authenticate with profile authn login before invoking any tenant command.

Q: Does tenant delete permanently remove a tenant?

No. tenant delete is a soft-delete that sets the tenant's valid_until to now. It is reversible, preserves cascade-linked rows, and the tenant still appears in tenant search.

tenant provides ADMIN-scope tenant lifecycle management for {{ product_name }}. Use it to create and bootstrap a tenant (role templates plus its OIDC resource-server configuration), search the tenant directory, update a tenant's mutable fields, and deactivate (soft-delete) a tenant.

Remote command group requiring an authenticated session

Every tenant command is a remote gRPC call. Before running any of them you must:

Create a host profile with profile hosts create.
Authenticate with profile authn login.

Select a non-default host profile for a single invocation with the global -p/--profile option placed before the command path (for example bin/admin.sh -p prod tenant search). Host connection profiles — including their embedded OIDC logins (with PIN-sealed tokens) — are stored under ${HOME}/.config/alpinepki/hosts/.

Commands in this group¶

Command	Purpose
`tenant create`	Create and bootstrap a tenant (role templates + OIDC)
`tenant search`	Search the tenant directory
`tenant update`	Update a tenant's name, display, or validity
`tenant delete`	Deactivate (soft-delete) a tenant

Subgroups¶

Subgroup	Purpose	Reference
`tenant db`	Manage a tenant's database connection configuration	tenant db
`tenant oidc`	Manage a tenant's OIDC resource-server configuration	tenant oidc
`tenant license`	Manage a tenant's license assignments	tenant license

Typical workflow¶

Create the tenant with tenant create, supplying its slug and OIDC issuer/audience.
Confirm it exists with tenant search.
Adjust mutable fields later with tenant update.
Deactivate it with tenant delete when it is no longer in use (reversible).

Group help¶

bin/admin.sh tenant --help

`tenant create`¶

Create and bootstrap a tenant. The command persists the tenant, entitles it to all TENANT-plane permissions, provisions its immutable per-tenant role templates (including rol-bootstrap-tenant), and stores the tenant's OIDC resource-server configuration gathered from the shared OIDC option group.

Syntax¶

bin/admin.sh tenant create [options]

Required options¶

Option	Description
`-n`, `--name`	Unique tenant name (slug)
`-i`, `--oidc-issuer-claim`	OpenID issuer claim expected during token validation
`-a`, `--oidc-audience-claim`	OpenID audience claim expected during token validation

Optional options¶

Show optional options

Option	Default	Description
`-d`, `--display`	tenant name	Tenant display name
`--valid-until`	none	Validity end as an ISO-8601 instant (e.g. `2027-01-01T00:00:00Z`)
`--oidc-token-mode`	`OIDC_TOKEN_MODE_JWT_LOCAL`	Token validation mode: `OIDC_TOKEN_MODE_JWT_LOCAL`, `OIDC_TOKEN_MODE_JWT_USERINFO`, `OIDC_TOKEN_MODE_OPAQUE_INTROSPECT`, or `OIDC_TOKEN_MODE_AUTO`
`--oidc-clock-skew-seconds`	`30`	Clock skew allowance in seconds (minimum 0)
`-O`, `--oidc-connect-timeout-ms`	`1500`	OIDC connect timeout in milliseconds
`--oidc-read-timeout-ms`	`1500`	OIDC read timeout in milliseconds (minimum 500)
`--[no-]oidc-use-discovery`	`--oidc-use-discovery`	Use OIDC endpoint discovery
`--oidc-discovery-url-override`	none	OpenID discovery URL override
`--oidc-jwks-url-override`	none	OpenID JWKS URL override
`--[no-]oidc-allow-user-info-fallback`	`--no-oidc-allow-user-info-fallback`	Allow OIDC UserInfo fallback
`--oidc-user-info-url-override`	none	OpenID UserInfo URL override
`--[no-]oidc-allow-introspection-fallback`	`--no-oidc-allow-introspection-fallback`	Allow OIDC token introspection fallback
`--oidc-introspection-url-override`	none	OpenID introspection URL override
`--oidc-introspection-client-id`	none	OpenID introspection client id
`--oidc-introspection-client-secret`	none	OpenID introspection client secret
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Conditionally required options¶

Condition	Required options
`--oidc-token-mode OIDC_TOKEN_MODE_OPAQUE_INTROSPECT`	`--oidc-allow-introspection-fallback`
`--no-oidc-use-discovery`	`--oidc-jwks-url-override`
`--no-oidc-use-discovery` plus `--oidc-allow-user-info-fallback`	`--oidc-user-info-url-override`
`--no-oidc-use-discovery` plus `--oidc-allow-introspection-fallback`	`--oidc-introspection-url-override`
`--oidc-allow-introspection-fallback`	`--oidc-introspection-client-id` and `--oidc-introspection-client-secret`

Validation rules

OIDC_TOKEN_MODE_OPAQUE_INTROSPECT requires --oidc-allow-introspection-fallback.
When discovery is disabled (--no-oidc-use-discovery), --oidc-jwks-url-override is mandatory.
With discovery disabled, --oidc-allow-user-info-fallback requires --oidc-user-info-url-override.
With discovery disabled, --oidc-allow-introspection-fallback requires --oidc-introspection-url-override.
--oidc-allow-introspection-fallback always requires both --oidc-introspection-client-id and --oidc-introspection-client-secret.

Example (local JWT validation with discovery)¶

bin/admin.sh tenant create \
  -n acme \
  -d "ACME Corporation" \
  --valid-until 2027-01-01T00:00:00Z \
  --oidc-issuer-claim https://idp.example.com/realms/acme \
  --oidc-audience-claim alpine-tenant-acme \
  -f json

Example (opaque token introspection)¶

bin/admin.sh tenant create \
  -n acme \
  --oidc-issuer-claim https://idp.example.com/realms/acme \
  --oidc-audience-claim alpine-tenant-acme \
  --oidc-token-mode OIDC_TOKEN_MODE_OPAQUE_INTROSPECT \
  --oidc-allow-introspection-fallback \
  --oidc-introspection-client-id alpine-introspect \
  --oidc-introspection-client-secret s3cr3t \
  -f yaml

Bootstrap the first tenant user

After creation, configure the tenant's IdP to emit a provisioned template (for example rol-bootstrap-tenant) in the first user's urn::alpine:roles claim so that user signs in with full tenant access.

`tenant search`¶

Search the tenant directory. Deactivated tenants (soft-deleted via valid_until) are included in results.

Syntax¶

bin/admin.sh tenant search [options]

Required options¶

This command has no command-specific required options.

Optional options¶

Show optional options

Option	Default	Description
`-q`, `--query`	none	Query string
`-m`, `--query-mode`	`QUERY_MODE_ILIKE`	Query mode: `QUERY_MODE_WEB`, `QUERY_MODE_PLAIN`, or `QUERY_MODE_ILIKE`
`-n`, `--query-page-number`	`1`	Start page (first page is page number 1)
`-s`, `--query-page-size`	`50`	Page size (minimum 1, maximum 250)
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Example¶

bin/admin.sh tenant search -q acme -m QUERY_MODE_ILIKE -n 1 -s 50 -f json

`tenant update`¶

Update a tenant's mutable fields (slug, display name, validity) identified by its immutable UUID. The UUID itself is never changed.

Syntax¶

bin/admin.sh tenant update [options]

Required options¶

Option	Description
`-u`, `--uuid`	UUID of the tenant to update

Conditionally required options¶

Condition	Required options
Always	At least one of `-n`/`--name`, `-d`/`--display`, or `--valid-until`

Validation rules

Supply at least one of --name, --display, or --valid-until; otherwise the command rejects the request as invalid input.
--valid-until must be a valid ISO-8601 instant (for example 2027-01-01T00:00:00Z).

Optional options¶

Show optional options

Option	Default	Description
`-n`, `--name`	unchanged	New tenant name (slug)
`-d`, `--display`	unchanged	New tenant display name
`--valid-until`	unchanged	New validity end as an ISO-8601 instant (e.g. `2027-01-01T00:00:00Z`)
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Example¶

bin/admin.sh tenant update \
  -u 6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f \
  -d "ACME International" \
  --valid-until 2028-01-01T00:00:00Z \
  -f json

`tenant delete`¶

Deactivate (soft-delete) a tenant by UUID. Deactivation sets the tenant's valid_until to the current time; it is reversible and preserves all cascade-linked rows. The tenant remains visible in tenant search.

Syntax¶

bin/admin.sh tenant delete [options]

Required options¶

Option	Description
`-u`, `--uuid`	UUID of the tenant to deactivate

Optional options¶

Show optional options

Option	Default	Description
`-f`, `--out-format`	`YAML`	Output format: `JSON` or `YAML`

Example¶

bin/admin.sh tenant delete -u 6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f -f json

Standard CLI options are documented in Global options.

FAQ¶

Do I need to log in before running tenant commands?

Yes. Every tenant command is a remote gRPC call. Create a host profile with profile hosts create, then authenticate with profile authn login before invoking any tenant command.

Does tenant delete permanently remove a tenant?

No. tenant delete is a soft-delete that sets the tenant's valid_until to now. It is reversible, preserves cascade-linked rows, and the tenant still appears in tenant search.

Which fields can tenant update change?

It changes the tenant's mutable fields only: the name (slug), display name, and validity. The immutable UUID is never changed, and you must supply at least one of --name, --display, or --valid-until.

What does tenant create bootstrap?

It persists the tenant, entitles it to all TENANT-plane permissions, provisions its immutable per-tenant role templates (including rol-bootstrap-tenant), and stores the tenant's OIDC resource-server configuration.

tenant command group¶

Commands in this group¶

Subgroups¶

Typical workflow¶

Group help¶

tenant create¶

Syntax¶

Required options¶

Optional options¶

Conditionally required options¶

Example (local JWT validation with discovery)¶

Example (opaque token introspection)¶

tenant search¶

Syntax¶

Required options¶

Optional options¶

Example¶

tenant update¶

Syntax¶

Required options¶

Conditionally required options¶

Optional options¶

Example¶

tenant delete¶

Syntax¶

Required options¶

Optional options¶

Example¶

FAQ¶

Related¶

`tenant` command group¶

`tenant create`¶

`tenant search`¶

`tenant update`¶

`tenant delete`¶