> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate the CloudX CLI with browser OAuth or a CLOUDX_API_KEY environment variable.

# Authentication

The CloudX CLI supports two authentication methods:

* Browser OAuth with `cloudx auth login`
* API-key authentication with the `CLOUDX_API_KEY` environment variable

Use browser OAuth for interactive local work. Use an API key for CI, scheduled jobs, scripts, and other non-interactive environments.

## Browser OAuth

`cloudx auth login` starts the browser-based OAuth sign-in flow and stores the resulting session locally.

### Sign In

Run:

```bash theme={null}
cloudx auth login
```

Follow the browser prompt, then return to your terminal.

### Check Status

Run:

```bash theme={null}
cloudx auth status
```

This command exits `0` when logged in and `1` when logged out or when the current sign-in session can't be used. When the provisioning service is reachable, it also shows the active organization, account, role, and expiration details.

### Sign Out

Run:

```bash theme={null}
cloudx auth logout
```

This signs out the current OAuth session stored by the CLI.

## API Key

API-key authentication lets the CLI run without an interactive browser session. The CLI reads the key from `CLOUDX_API_KEY` and sends it to CloudX as a bearer token.

When `CLOUDX_API_KEY` is set, the CLI uses it instead of any stored OAuth session.

Only administrators can create, manage, and revoke API keys.

### Create An API Key

1. Open [https://app.cloudx.io/settings/api-keys](https://app.cloudx.io/settings/api-keys).
2. Sign in as an administrator if prompted.
3. Confirm you are on **Settings > API Keys**.
4. Create an API key for your CLI workflow.
5. Copy the key value when it is shown.

Choose permissions based on the commands the key needs to run:

| Permission            | Allows                                               |
| --------------------- | ---------------------------------------------------- |
| `reports:read`        | `cloudx report ...` commands                         |
| `auctions:read`       | `cloudx auction ...` commands                        |
| `configuration:read`  | `cloudx config show` and `cloudx config history`     |
| `configuration:write` | `cloudx config edit ...` and `cloudx config publish` |

### Use The API Key

Set the key in your shell:

```bash theme={null}
export CLOUDX_API_KEY='YOUR_API_KEY'
```

Then run CLI commands normally:

```bash theme={null}
cloudx auth status
cloudx report dashboard --period yesterday
cloudx auction list --period today --test-mode all
cloudx config show
```

For CI or scheduled jobs, store the key in your secret manager and expose it to the job as `CLOUDX_API_KEY`.

### Verify The API Key

Run:

```bash theme={null}
cloudx auth status
```

With `CLOUDX_API_KEY` configured, the command validates the key with CloudX and prints API-key details such as key name, key ID, organization ID, account ID, account type, and permissions.

If verification fails, check that `CLOUDX_API_KEY` is set to the full key value and that the key has not been deleted or revoked in CloudX.

### Stop Using An API Key

Unset the environment variable:

```bash theme={null}
unset CLOUDX_API_KEY
```

After unsetting it, the CLI returns to using the stored OAuth session, if one exists. To revoke the key itself, an administrator must delete it from [Settings > API Keys](https://app.cloudx.io/settings/api-keys).

`cloudx auth logout` only signs out the stored OAuth session. It does not revoke API keys.

## Related

* [CloudX CLI Overview](/en/cli)
* [Installation](/en/cli/installation)
* [Reporting Commands](/en/cli/reporting)
* [Examples](/en/cli/examples)