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

# CLI authentication

> Choose how to authenticate the Omni CLI with your instance: OAuth for streamlined setup or API keys for manual control.

The Omni CLI supports two authentication methods. Choose the one that best fits your needs:

|                  | OAuth                                         | API key                                                        |
| ---------------- | --------------------------------------------- | -------------------------------------------------------------- |
| Best for         | Individual users who want quick, secure setup | Admins managing keys centrally, or automated workflows (CI/CD) |
| Setup complexity | Low - browser flow                            | Medium - manual configuration                                  |
| Key management   | Automatic                                     | Manual                                                         |
| Token expiry     | 8 hours (auto-refreshes)                      | None                                                           |
| User permissions | Uses your permissions                         | Uses key creator's permissions                                 |

## OAuth authentication

OAuth lets the CLI connect to Omni without requiring you to manually create and manage API keys. When you authenticate with `omni config login`, Omni creates an API key on your behalf and links it to your user account.

<Note>
  CLI OAuth PATs are different from standard PATs. See the [CLI OAuth PATs section](#cli-oauth-pats) for more information.
</Note>

### Requirements

To use OAuth authentication with the CLI, your organization must have:

* **Personal access tokens (PATs)** enabled - Organization Admins can activate them by going to **Settings > API access > Personal tokens**

### How it works

When you authenticate the CLI using OAuth, the flow looks like this:

1. Run `omni config login` in your terminal.
2. Your browser opens to an authorization page for your Omni organization.
3. Review the permissions on the authorization page.
4. Click **Authorize**.
5. The CLI receives the tokens and stores them securely.

After authorization, all CLI commands use your Omni permissions and access controls. The flow uses OAuth 2.1 with PKCE for security.

### CLI OAuth PATs

When you authenticate with `omni config login`, Omni automatically creates a special PAT called a **CLI OAuth PAT**. These differ from standard PATs in a few ways:

<Steps>
  <Step title="Any user can create one" noAnchor>
    Standard PATs require **Restricted Querier** or higher permissions, but CLI OAuth PATs are created automatically for any user who completes the OAuth flow.
  </Step>

  <Step title="Access tokens expire after 8 hours" noAnchor>
    For security, CLI access tokens expire after 8 hours. The CLI automatically refreshes tokens using refresh token rotation, so you don't need to worry about expiration during normal usage.
  </Step>

  <Step title="Refresh tokens rotate on each use" noAnchor>
    When the CLI refreshes your access token, it receives a new refresh token and the old one is invalidated. This prevents replay attacks.
  </Step>

  <Step title="Permissions reflect the user's in-app permissions" noAnchor>
    CLI OAuth PATs inherit the creating user's in-app permissions.
  </Step>

  <Step title="Not visible in Omni">
    CLI OAuth PATs are not currently visible in Omni.
  </Step>
</Steps>

For a full comparison of all API key types in Omni, refer to the [API authentication](/api/authentication) documentation.

### Authenticating with OAuth

To authenticate the CLI with OAuth:

```bash theme={null}
omni config login
```

Your browser opens to the authorization page. After you authorize, the CLI is ready to use.

## API key authentication

API key authentication gives you direct control over key creation and management. This approach is useful when:

* You need to manage API keys centrally for your organization
* You're setting up automated workflows or CI/CD pipelines
* You want to use a service account rather than individual user credentials
* You prefer tokens that don't expire

### How it works

1. Create an [API key in Omni](/api/authentication)
2. Set the API key as an environment variable or configure it during `omni config init`
3. The CLI includes the key in all requests to Omni

### Authenticating with an API key

You can provide your API key in two ways:

**Option 1: Environment variable**

```bash theme={null}
export OMNI_API_TOKEN=omni_osk_...
```

**Option 2: During configuration**

```bash theme={null}
omni config init
```

When prompted, enter your API token.

## Troubleshooting

### OAuth issues

<AccordionGroup>
  <Accordion title="Personal Access Tokens aren't enabled (403 error)">
    Ask an admin to enable PATs: **Settings > API access > Personal tokens**
  </Accordion>

  <Accordion title="Authorization flow doesn't start">
    * Verify your browser is set as the default application for HTTP links
    * Check that your Omni instance is accessible from your browser
    * Try running `omni config login --help` to verify the CLI is properly installed
  </Accordion>

  <Accordion title="Authorization fails after clicking &#x22;Authorize&#x22;">
    * Check that your browser allows redirects to localhost
    * Verify you have permission to create API keys in your organization
    * Try running `omni config login` again
  </Accordion>

  <Accordion title="Token expired errors after 8 hours">
    The CLI automatically refreshes tokens. If you see this error:

    * Run `omni config login` again to re-authenticate
    * Check that your refresh token hasn't been revoked in Omni settings
  </Accordion>
</AccordionGroup>

### API key issues

<AccordionGroup>
  <Accordion title="Authentication fails">
    * Verify the API key is correct and hasn't been revoked
    * Check that the key has appropriate permissions
    * Ensure you're using the correct instance URL
    * Try setting `OMNI_API_TOKEN` directly in your environment
  </Accordion>
</AccordionGroup>

### General issues

<AccordionGroup>
  <Accordion title="Commands fail after successful authentication">
    * Confirm the API key is active in your Omni settings
    * Verify you have access to the resources you're trying to access
    * Check that your Omni user permissions allow the operation
  </Accordion>
</AccordionGroup>

## Next steps

Ready to start using the CLI? See the [quickstart guide](/developers/cli/quickstart) to run your first commands.