Authentication

oneocto auth login authenticates you against one Octo deployment and saves that tenant so later commands run without re-entering credentials.

The CLI can hold several saved tenants at once — for example a dev tenant and a production tenant — and runs against the default unless a command overrides it with --tenant.

Key concepts

Term	Definition
Tenant	A saved login: a slug, an API base URL, identity-provider settings, and an optional default space.
Default tenant	The tenant used when a command does not pass --tenant.
Space	The scope most resources belong to. Saved per tenant and overridable with --space-id.
Session	The cached tokens the CLI reuses and refreshes between commands.

Sign in

The simplest form asks for what it needs and works the rest out for you:

oneocto auth login

Paste the URL you already use in the browser and the CLI reads the tenant and environment from it. The path is ignored, so any page URL works:

oneocto auth login --url https://acme.oneocto.com

Other useful forms:

oneocto auth login --env dev          # local | dev | prod
oneocto auth login --local            # shorthand for --env local
oneocto auth login --set-default      # also make this the default tenant

Option	Purpose
--tenant <slug>	Tenant slug to sign in as.
--email <email>	Login email, prompted for when omitted.
--password <password>	Login password. Prefer omitting it so the CLI prompts instead of leaving it in shell history.
--url <url>	Deployment URL to read the tenant and environment from.
--env <name>	Deployment to authenticate against: local, dev, or prod. Defaults to dev.
--api-base-url <url>	Explicit API base URL, bypassing --env.
--set-default	Save this tenant as the default.

Pass --password only in an automated context where the value comes from a secret store. In a terminal, let the CLI prompt for it.

Confirm who you are

oneocto auth whoami

The response resolves the saved credentials to a user, so it is the fastest way to confirm which tenant and identity a command will run as.

Set a default space

Most resources are space-scoped. Save a default once and later commands stop needing --space-id:

oneocto list spaces
oneocto tenant use

In an interactive terminal, oneocto tenant use shows a cursor-driven picker. Pass a slug directly when scripting:

oneocto tenant use acme

Manage saved tenants

oneocto tenant list                             # every saved tenant
oneocto tenant use [slug]                       # set the default tenant
oneocto tenant edit <slug> --space-id <id>      # update saved metadata
oneocto tenant edit <slug> --clear-space-id     # drop the saved default space
oneocto tenant remove <slug> --yes              # remove a tenant and its auth state

tenant edit also updates the API base URL and identity-provider settings when a deployment moves.

Sign out

oneocto auth logout                  # the default tenant
oneocto auth logout --tenant acme    # one specific tenant

Signing out removes the saved login for that tenant. Other saved tenants are untouched.

Authenticate without an interactive login

CI jobs and agent runtimes can skip the saved login entirely by supplying a pre-issued token:

ONEOCTO_API_URL=https://api.acme.oneocto.com \
ONEOCTO_ACCESS_TOKEN=<token> \
ONEOCTO_SPACE_ID=<space-id> \
oneocto list workflows --minified

Store these as secrets in your CI provider. Never commit them.

Where credentials are stored

Tenant metadata — slugs, API URLs, the default space — lives in the config directory, which ONEOCTO_CONFIG_DIR can relocate. Credentials are kept in the OS keychain and are never written to the config file.

FAQ

How do I switch between a dev and a production tenant? Sign in to each once, then either set a default with oneocto tenant use or pass --tenant <slug> on individual commands.

Do I have to log in again every day? No. The CLI caches the session and refreshes it. Log in again only when a refresh fails or you have signed out.

A command failed with a permission error. Is that an authentication problem? Usually not. Authentication decides who you are; roles and permissions decide what you can do. Confirm your identity with oneocto auth whoami, then check the assigned role in Roles.

Can the CLI use an API key instead? No. API keys authenticate external systems calling the platform. The CLI authenticates as a user.

Related pages

• Installation - install the CLI and set the configuration variables
• Command Reference - the --tenant and --space-id overrides in context
• Roles - what a signed-in user is permitted to do
• Spaces - how spaces scope the records the CLI returns