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

​
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.
CLI OAuth PATs are different from standard PATs. See the CLI OAuth PATs section for more information.

​
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:
1

Any user can create one

Standard PATs require Restricted Querier or higher permissions, but CLI OAuth PATs are created automatically for any user who completes the OAuth flow.
2

Access tokens expire after 8 hours

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

Refresh tokens rotate on each use

When the CLI refreshes your access token, it receives a new refresh token and the old one is invalidated. This prevents replay attacks.
4

Permissions reflect the user's in-app permissions

CLI OAuth PATs inherit the creating user’s in-app permissions.
5

Not visible in Omni

CLI OAuth PATs are not currently visible in Omni.
For a full comparison of all API key types in Omni, refer to the API authentication documentation.

​
Authenticating with OAuth

To authenticate the CLI with OAuth:
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
  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
Option 2: During configuration
When prompted, enter your API token.

​
Troubleshooting

​
OAuth issues

Ask an admin to enable PATs: Settings > API access > Personal tokens
  • 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
  • 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
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

​
API key issues

  • 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

​
General issues

  • 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

​
Next steps

Ready to start using the CLI? See the quickstart guide to run your first commands.