Connecting to Alteryx One

ayx talks to Alteryx One over its /v4 REST API. There are two supported user-credential methods, and both are first-class:

Email one-time passcode (OTP) is the default interactive method and the quickest first run. It asks for a 6-digit code and your workspace password. It is a time-limited login: the access token it returns expires after 30 days, does not renew automatically, and you will sign in again.
OAuth API access/refresh credentials are the durable method. Paste a Client ID and Refresh Token once from the Alteryx One UI; ayx stores the pair in the operating-system keyring and renews short-lived access tokens silently from then on, without falling back to OTP. This suits a person who would rather not re-authenticate every 30 days just as much as it suits automation, CI, and agents.

Secure storage protects either credential at rest. It does not extend how long a credential lasts.

These are different credential types. An OAuth refresh token is not an OTP, and an API token managed by ayx one token is not automatically the same thing as the OAuth access/refresh pair used by ayx one login --auth-method oauth-refresh.

The quick path

ayx onboard

The wizard collects your email and workspace URL (and, if you give it a bare workspace id, your regional base URL) and offers to log you in on the spot — see Getting started. It uses email OTP for the interactive path, which is time-limited to 30 days. For a login that renews itself, configure an OAuth API access/refresh pair as described below — that is the right choice for people and automation alike.

A beginner’s checklist

Open PowerShell on Windows, or Terminal on macOS/Linux.
Run ayx onboard.
Paste the workspace URL from your browser when asked. (If you paste a bare workspace id instead, the wizard also asks for your Alteryx One regional base URL, because an id does not identify its region.)
At Log in now [Y/n]: the default is Yes — pressing Enter signs you in and sends a real one-time passcode. Enter the emailed 6-digit code and your workspace password, then press Enter when asked to save the password.
Run ayx one workspace current to confirm the connection.

That sign-in lasts 30 days and will not renew itself. To avoid the monthly re-authentication — and for any computer, CI job, or agent — use the OAuth checklist below instead. It renews access tokens from a stored refresh token rather than asking a person for a new email code.

Signing in

ayx one login

With no flags this runs the email-OTP flow:

A 6-digit passcode is emailed to your account address.
ayx prompts you for the passcode, then for your workspace password.
On success it stores a 30-day access token in the active profile. This token does not renew automatically; when it expires you run ayx one login again.
On the first interactive login, it asks whether to save the workspace password securely for future logins. Press Enter for the default Yes, or answer n to decline. Saving it means the next sign-in does not prompt for the password — it does not keep the token from expiring.

The successful login prints an Authentication Successful! confirmation only after the credentials and profile state have been persisted. It also reports token expiry and, when available, the authenticated workspace id and name.

Profile selection is --profile <name>, then AYX_PROFILE, then the active profile pointer, then the central default profile.

It reads three fields from your profile — your email (from the onboarding prompt) and your workspace id + region (parsed from the workspace URL you paste during onboarding):

Field	Where it comes from
`account_email`	The address you sign in to Alteryx One with
`workspace_gid`	The workspace id (a ULID) in your workspace URL — required by the sign-in handshake
`base_url`	Your Alteryx One region host, e.g. `https://us1.alteryxcloud.com` (also read from the URL)

If the token later expires, just run ayx one login again. If signing in every 30 days is not what you want, set up the durable OAuth credential below instead.

For an OAuth credential, access-token renewal is automatic. If the provider has expired or revoked the refresh token, import a newly issued pair using the OAuth instructions below; the CLI will not silently send an OTP instead.

The durable path: OAuth API access/refresh credentials

Use this method whenever you want a login that keeps working: a person who would rather not re-authenticate every 30 days, and any CLI that must run unattended. Create or obtain an OAuth2.0 API-token pair from the Alteryx One administration experience. Run one command, paste the visible Client ID shown on the OAuth2.0 API Tokens page, then paste the hidden Refresh Token from the generated-token dialog. The CLI verifies the pair before saving it in the operating-system keyring rather than the profile file:

ayx one login --profile local-dev --workspace-id <workspace-id> \
  --oauth-api-token \
  --secret-policy secure

The --profile, --workspace-id, and --secret-policy flags above are optional; ayx one login --oauth-api-token on its own uses the active profile and its defaults.

After that one-time setup, use ayx normally. --oauth-api-token is not the email one-time-passcode flow. The access token lasts only a few minutes, but the CLI renews it automatically with the securely stored refresh token. You should not have to paste it again until the provider’s configured refresh-token lifetime (up to 365 days), unless it is revoked or deleted in Alteryx One.

Once it is configured, do not use login as a routine step: run normal ayx one ... commands and they renew access when necessary. A bare ayx one login only confirms that OAuth is configured; ayx one auth diagnose performs a live check, and ayx one login --oauth-api-token intentionally replaces the saved credential.

For CI, a secret manager, or other non-interactive automation, use an environment variable or stdin instead:

# The environment variable is read for this import only; secure persistence
# stores the resulting credential in the OS keyring.
ayx one login --profile local-dev --workspace-id <workspace-id> \
  --oauth-api-token \
  --refresh-token-env AYX_ONE_API_REFRESH_TOKEN \
  --secret-policy secure

# Or, on macOS/Linux:
printf '%s' "$AYX_ONE_API_REFRESH_TOKEN" |
  ayx one login --profile local-dev --workspace-id <workspace-id> \
    --auth-method oauth-refresh --refresh-token-stdin --secret-policy secure

# PowerShell:
$env:AYX_ONE_API_REFRESH_TOKEN |
  ayx one login --profile local-dev --workspace-id <workspace-id> \
    --auth-method oauth-refresh --refresh-token-stdin --secret-policy secure

On an intentional replacement, press Enter at the Client ID prompt to retain the saved value or paste a replacement. For automation, the client ID can be configured as alteryx_one.oauth_client_id or supplied through AYX_ONE_OAUTH_CLIENT_ID; the token endpoint can be configured as alteryx_one.token_endpoint_url or AYX_ONE_TOKEN_ENDPOINT_URL. The refresh token is bound to the selected workspace and profile. After import, ordinary commands use the keyring-backed pair; no OTP prompt is expected. Automatic refresh uses a short safety window and persists any provider-issued replacement refresh token while preventing replay of an applied mutation after an uncertain response.

Provider token exchange and local keyring storage are separate systems. A process or keyring failure immediately after a provider accepts a rotating refresh token can leave the local state in doubt; ayx will not blindly retry that exchange. Re-import a fresh access/refresh pair if the command reports that persistence failed.

Do not put token values in command arguments, checked-in YAML, shared logs, or documentation. --refresh-token <value> remains a compatibility option, but the env/stdin forms are the release-safe choices.

Credential persistence

Secure operating-system storage is the default. It protects credentials at rest; it does not change how long any credential remains valid. The first interactive workspace-password login offers to save the password in the OS keyring; Enter accepts the save, while n keeps the password session-only. --save-workspace-password remains an optional automation shorthand for the default email-OTP flow.

If secure storage is unavailable, --secret-policy plaintext is an explicit fallback and requires affirmative consent. The standalone login command rejects --secret-policy session because its process exits immediately and cannot retain a usable session. OAuth refresh rotation is automatic only when the refresh credential is stored in a supported secure keyring; environment-backed or inline credentials are not rewritten in place.

You usually won’t need these, but they’re there:

ayx one login --refresh-token-env NAME / --refresh-token-stdin — import an OAuth refresh token without exposing its value in process arguments.
ayx one login --access-token-env NAME / --access-token-stdin — import an access token without exposing its value; this is a non-rotating compatibility path and cannot select oauth-refresh by itself.
ayx one login --refresh-token <t> / --access-token <t> — compatibility imports; avoid these forms in shared terminals and automation logs.

The OAuth refresh flows use an OAuth client, so they need an oauth_client_id in your profile (or --client-id). The default email-OTP flow does not.

ayx one login also accepts --browser (PKCE authorization-code) and --device (device-code). Both are hidden from --help and are not recommended: neither has ever been validated against a live Alteryx One tenant, and the device authorization endpoint is derived by string substitution on the token endpoint with no discovery lookup. Both grants would also have to be enabled on the Alteryx OAuth client, with http://localhost:<port> registered as a redirect URI for the browser flow.

They still run if you type them, so they can be re-tested. If you need a durable credential today, use ayx one login --oauth-api-token.

Confirm it worked

ayx doctor auth     # checks the token path end to end
ayx whoami          # shows the workspace you're connected to

ayx doctor auth reports each One credential’s credential_kind, whether it renews_automatically, and when its access token expires. For an email-OTP credential it also suggests the upgrade to --oauth-api-token. That is an upgrade, not a repair: an unexpired OTP credential is working exactly as designed.

Once that expiry has passed, doctor auth says so: one_status becomes expired, the row warns, and the guidance names the remedy — sign in again with ayx one login. The credential is out of date, not malformed. An oauth_refresh credential is judged differently, because it mints a new access token on demand; an expired access token there is self-healing and is not reported as a problem.

If doctor auth passes but a command later fails with an auth error, check ayx one auth status and ayx one auth diagnose. An OTP credential may need a new ayx one login; an OAuth credential usually needs no action unless its refresh token has expired or been revoked, in which case import a newly issued pair with --auth-method oauth-refresh.

Multiple workspaces

One profile can hold a separate token per workspace. Bind a login to a specific workspace, then switch which one is active:

ayx one login --workspace-id <id>   # store this workspace's token
ayx one workspace use <id|gid|saved-name> # make it the active one

Each workspace keeps its own credential method and token pair. Switching workspaces does not copy credentials or change another workspace’s OTP/OAuth policy.

See Profiles & configuration for the full model.

Auth-transport safety

The email-OTP first-login flow is pure-HTTP (reqwest). There is no browser, Python, or Playwright dependency.

During the OIDC flow, ayx applies two transport-level guards:

Redirect-host allowlist. The redirect follower only accepts the configured Alteryx domain and its subdomains. An off-domain redirect (e.g. to an unrelated host) is rejected with an error before any credential is sent.
Interaction-id validation. The OIDC interaction id is validated for shape (6–128 characters, restricted charset) before use. A malformed value from the server is rejected rather than forwarded.

Response bodies are redacted in auth-flow error output so credential material does not appear in logs or terminal output.

When you sign in on a machine where no OS keyring backend is available, ayx asks for explicit consent before storing credentials inline in the config file (plaintext at rest). Configuring a keyring backend — the system keychain on macOS, libsecret on Linux, or Windows Credential Manager — keeps credentials out of the profile and suppresses the warning.

Connecting to Alteryx Server (optional)

If you also administer Alteryx Server, add a server: block to your profile with the Server API host and credentials:

server:
  api:
    base_url: https://your-server.example.com
    client_id: <id>
    client_secret: <secret>

The ayx server commands — status, diagnostics, upgrade planning, and more — then run against it. ayx onboard can set this up interactively too.