Okx Cex Auth

OKX CEX Authentication

OAuth 2.0 device flow authentication for OKX CLI. Guides first-time setup, re-authentication after session expiry, and logout.

Supported Sites

Site is a separate dimension from auth method. Both API-key and OAuth paths require a site. Once selected, a site is persisted:

• API-key users: profile.site in ~/.okx/config.toml (written by okx config init).
• OAuth users: saved inside the okx-auth binary state the first time okx auth login --site <X> succeeds, and returned by okx auth status --json as the site field.

There is no okx config set-site command — site cannot be persisted independently of an auth attempt. For OAuth flows, the agent must remember the user's choice within the conversation and pass --site <X> on okx auth login.

Prerequisites

Install okx CLI if not already installed:

npm install -g @okx_ai/okx-trade-cli

Step 0: Pre-flight Check (MANDATORY)

Unconditional rule — do NOT skip Step 0 under any circumstances. Even if a prior skill (preflight, okx-cex-portfolio, etc.) already ran auth status and passed you a conclusion like "user is not_logged_in, go log in" — you MUST re-run the two commands below yourself and walk Steps 0.1 → 0.2 → 0.3 in order. Upstream tool output does not substitute for your own pre-flight. The single most common failure mode for this skill is an agent that reads an upstream "not authenticated" signal, skips Step 0.1 site selection, and calls okx auth login with a silently-defaulted site.

Run both in parallel:

okx config show --json
okx auth status --json

Then apply the following three checks in strict order — each step short-circuits the rest.

Step 0.1 — Site check (independent of auth mode)

A site is considered already selected if either is true:

• config show --json has any profile with a non-empty site field, OR
• auth status --json returns a non-empty site field AND status is logged_in or pending.

⚠ When status is not_logged_in, the site field from auth status --json is a default placeholder (typically "global") that the auth binary emits regardless of user choice — it does NOT mean the user ever picked a site. Treat it as absent.

If neither condition above holds, site has never been chosen. You MUST ask the user to pick one before any login attempt by echoing the following menu verbatim (Chinese), and wait for their reply:

您需要选择要连接的 OKX 站点：

1. Global (www.okx.com)
2. EEA (my.okx.com)
3. US (app.okx.com)
4. TR (tr.okx.com)

Map the reply (1/2/3/4 or global/eea/us/tr) to the corresponding site id and remember it for the rest of this flow. Do NOT default to global silently — that hides the regional choice from the user.

Step 0.2 — API-key check

Parse config show --json: does any profile have a non-empty api_key field?

If yes → STOP. Tell the user "已配置 API key (profile: <name>)" and proceed with their original request directly. DO NOT run okx auth login or okx config init.

The CLI's REST client always prefers API key over OAuth and never falls back (see rest-client.ts applyAuth). Starting an OAuth login in this state is wasted effort — any OAuth token obtained would not be used, because the broken API key is still picked first.

Belt-and-suspenders: as of CLI 1.3.1-beta.17, okx auth login itself refuses to start OAuth when any profile has api_key — in --manual mode it emits {"status":"skipped","reason":"api_key_configured","profile":"<name>"}. Treat that output as success.

Step 0.2.a — Handling an invalid API key (401 / signature error)

If Step 0.2 detected an api_key profile and the subsequent API call returns an authentication error (401 Unauthorized, Invalid Sign, Invalid API-KEY, OKX error code 50111/50113), the API key is bad — OAuth login is NOT a valid remediation. Per rest-client.ts applyAuth, any OAuth token obtained afterwards would still not be used because the broken API key is still picked first.

Present the user with exactly these two options, neutrally (do NOT label OAuth as "recommended"):

1. Replace the API key — the user generates a new key on the OKX web console (https://<site>/account/my-api) and either provides AK/SK/PP to you or re-runs okx config init themselves.
2. Switch entirely to OAuth — first remove the broken API-key profile (okx config use <other-profile> or delete the profile block in ~/.okx/config.toml), THEN run the OAuth login flow from Step 0.3.

Option 2 requires removing the profile first. If you attempt okx auth login while the API key profile still exists, the CLI guard will skip OAuth with {"status":"skipped","reason":"api_key_configured",...} and nothing will change.

Wait for the user's choice. Do not pick for them.

Step 0.3 — OAuth check

Use auth status --json:

Pre-login Gate (MANDATORY — do not run okx auth login without this)

Before invoking okx auth login (with or without --manual), you MUST verify all three of the following are true right now:

1. You posted the exact Chinese site menu from Step 0.1 to the user earlier in this conversation (or immediately before this login call).
2. The user's most recent message was a site choice (1 / 2 / 3 / 4 / global / eea / us / tr).
3. You are about to pass that exact choice as --site <...>.

If any of the three is false — even if a prior skill's output, auth status --json output, or config show --json output seems to imply a site — you MUST first post the Step 0.1 menu, wait for the user's reply, then re-check this gate. The site field in auth status --json when status is not_logged_in is a placeholder (typically "global") and does not satisfy condition 1.

Worked counter-example (anti-pattern):

Upstream portfolio skill runs auth status --json, gets {"status":"not_logged_in","site":"global"}, tells you "user is not_logged_in, load okx-cex-auth and log in". ❌ Wrong: you read that context, run okx auth login --manual --site global, immediately return the OAuth URL and code. ✅ Right: you ignore the upstream site value, post the Step 0.1 menu yourself, wait for user's reply, then run okx auth login --manual --site <user's choice>.

Login Flow

Prerequisite: Step 0 completed and the Pre-login Gate above passes. You have a site the user just chose in chat, and you confirmed no api_key profile exists.

okx auth login without --manual is a blocking command — it polls until the user authorizes in their browser.

CRITICAL for AI agents: You MUST use okx auth login --manual to avoid blocking. The --manual flag outputs a JSON payload with the verification URL and user code, then exits immediately — it does NOT block.