Administer your organization with the CLI

Create and manage API keys, configure OAuth authentication for end users, and set up white-label billing for your organization.

Find your IDs

To find your organization ID:

viam organizations list

To find location IDs:

viam locations list

To find machine IDs:

viam machines list --organization=<org-id> --all

Manage API keys

Organization API key

Create an API key with organization-level access. Organization keys have the organization_owner role with full read and write access to every resource in the organization.

viam organizations api-key create --org-id=<org-id> --name=my-org-key

The CLI prints the key ID and key value. Save both immediately; the key value is only shown once.

Successfully created key:
Key ID: abcdef12-3456-7890-abcd-ef1234567890
Key Value: your-secret-key-value

Location API key

Create an API key scoped to a specific location. Location keys have the location_owner role.

viam locations api-key create --location-id=<location-id> --name=my-location-key

Machine API key

Create an API key scoped to a single machine. Machine keys have the robot_owner role.

viam machines api-key create --machine-id=<machine-id>

Set up OAuth

OAuth setup is CLI-only. There is no web UI for these operations.

Enable the auth service

viam organizations auth-service enable --org-id=<org-id>

Set branding

viam organizations logo set --org-id=<org-id> --logo-path=./logo.png

viam organizations support-email set --org-id=<org-id> --support-email=support@example.com

Create an OAuth application

viam organizations auth-service oauth-app create \
  --org-id=<org-id> \
  --client-name=my-app \
  --client-authentication=unspecified \
  --url-validation=exact_match \
  --pkce=required \
  --enabled-grants=authorization_code \
  --redirect-uris=https://example.com/callback \
  --logout-uri=https://example.com/logout \
  --origin-uris=https://example.com

On success, the CLI prints the client ID and client secret. Save both values immediately; you need the client ID for subsequent commands.

Manage OAuth applications

List all OAuth applications:

viam organizations auth-service oauth-app list --org-id=<org-id>

Get details on a specific application:

viam organizations auth-service oauth-app read \
  --org-id=<org-id> \
  --client-id=<client-id>

Update an application:

viam organizations auth-service oauth-app update \
  --org-id=<org-id> \
  --client-id=<client-id> \
  --client-name=updated-name

Delete an application:

viam organizations auth-service oauth-app delete \
  --org-id=<org-id> \
  --client-id=<client-id>

Disable the auth service

viam organizations auth-service disable --org-id=<org-id>

Configure white-label billing

Billing service setup is CLI-only.

Enable billing. The address format is "line1, line2 (optional), city, state, zipcode":

viam organizations billing-service enable --org-id=<org-id> --address="123 Main St, Springfield, IL, 62704"

Get billing configuration:

viam organizations billing-service get-config --org-id=<org-id>

Update billing:

viam organizations billing-service update --org-id=<org-id> --address=<billing-address>

Disable billing:

viam organizations billing-service disable --org-id=<org-id>

Related pages

• Manage access for role-based access control in the Viam app
• Authenticate end users with OAuth for OAuth setup details
• White-labeled billing for billing fragment configuration
• CLI reference for the complete organizations command reference