# 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.

##### Prerequisites

You need the Viam CLI installed and authenticated. See [Viam CLI overview](https://docs.viam.com/cli/overview/) for installation and authentication instructions.

## Find your IDs

To find your organization ID:

```sh
viam organizations list
```

To find location IDs:

```sh
viam locations list
```

To find machine IDs:

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

## Manage locations

List all locations in your organization:

```sh
viam locations list
```

If you belong to multiple organizations, specify which one:

```sh
viam locations list --organization=<org-id>
```

If you have set a default organization with `viam defaults set-org`, the CLI uses it automatically.

## 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.

```sh
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.

```sh
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.

```sh
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.

```sh
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. Before OAuth can be enabled, first ensure a logo and support email are set on your organization.

### Set branding

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

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

### Enable the auth service

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

### Create an OAuth application

```sh
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:

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

Get details on a specific application:

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

Update an application:

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

Delete an application:

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

### Disable the auth service

```sh
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`:

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

Get billing configuration:

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

Update billing:

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

Disable billing:

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