use-railway: railway-api.sh fails with Railway CLI 4.x auth config

[dringrayson]

Summary

plugins/railway/skills/use-railway/scripts/railway-api.sh currently reads Railway auth only from ~/.railway/config.json:user.token.

Railway CLI 4.x can store the authenticated session under user.accessToken, with user.refreshToken and user.tokenExpiresAt, instead of user.token. In that case railway whoami --json works, but the helper exits with No Railway token found.

Affected paths

• plugins/railway/skills/use-railway/scripts/railway-api.sh
• plugins/railway/skills/use-railway/references/request.md
• AGENTS.md
• CLAUDE.md
• plugins/railway/.claude-plugin/plugin.json if the fix is shipped as a skill/plugin content update

Current behavior

The helper has this auth lookup:

TOKEN=$(jq -r '.user.token' "$CONFIG_FILE")

if [[ -z "$TOKEN" || "$TOKEN" == "null" ]]; then
  echo '{"error": "No Railway token found. Run: railway login"}'
  exit 1
fi

On a machine authenticated with Railway CLI 4.42.1, the config shape was:

user.accessToken
user.refreshToken
user.tokenExpiresAt

There was no user.token.

As a result, this failed:

plugins/railway/skills/use-railway/scripts/railway-api.sh \
  'query { me { name email } }'

With:

{"error": "No Railway token found. Run: railway login"}

But this succeeded:

railway whoami --json

Manually using ~/.railway/config.json:user.accessToken as the bearer token against https://backboard.railway.com/graphql/v2 also succeeded.

Expected behavior

railway-api.sh should work when the Railway CLI is authenticated, including with Railway CLI 4.x config.

It should resolve auth in this order:

1. RAILWAY_API_TOKEN, useful for automation.
2. ~/.railway/config.json:user.accessToken, current Railway CLI 4.x session token shape.
3. ~/.railway/config.json:user.token, legacy CLI config fallback.

If user.accessToken is present and user.tokenExpiresAt is expired, the helper could run railway whoami --json once to let the CLI refresh the session, then re-read the config.

Suggested fix

Centralize compatibility in railway-api.sh so all downstream skill scripts inherit the behavior.

Suggested token lookup shape:

CONFIG_FILE="$HOME/.railway/config.json"

if [[ -z "${RAILWAY_API_TOKEN:-}" && ! -f "$CONFIG_FILE" ]]; then
  echo '{"error": "Railway config not found and RAILWAY_API_TOKEN is not set. Run: railway login"}'
  exit 1
fi

read_token() {
  if [[ -n "${RAILWAY_API_TOKEN:-}" ]]; then
    TOKEN="$RAILWAY_API_TOKEN"
    TOKEN_SOURCE="RAILWAY_API_TOKEN"
    TOKEN_EXPIRES_AT=""
    return
  fi

  TOKEN=$(jq -r '.user.accessToken // .user.token // empty' "$CONFIG_FILE")
  TOKEN_SOURCE=$(jq -r '
    if .user.accessToken then "user.accessToken"
    elif .user.token then "user.token"
    else "none"
    end
  ' "$CONFIG_FILE")
  TOKEN_EXPIRES_AT=$(jq -r '.user.tokenExpiresAt // empty' "$CONFIG_FILE")
}

read_token

if [[ -z "$TOKEN" ]]; then
  echo '{"error": "No Railway token found. Expected RAILWAY_API_TOKEN, ~/.railway/config.json user.accessToken, or legacy user.token. Run: railway login"}'
  exit 1
fi

if [[ "$TOKEN_SOURCE" == "user.accessToken" && "$TOKEN_EXPIRES_AT" =~ ^[0-9]+$ ]]; then
  NOW=$(date +%s)

  if [[ "$TOKEN_EXPIRES_AT" -le "$NOW" ]]; then
    if ! command -v railway >/dev/null 2>&1; then
      echo '{"error": "Railway access token is expired and the railway CLI is not installed, so it cannot be refreshed. Run: railway login"}'
      exit 1
    fi

    if ! railway whoami --json >/dev/null 2>&1; then
      echo '{"error": "Railway access token is expired and refresh failed. Run: railway login"}'
      exit 1
    fi

    read_token

    if [[ -z "$TOKEN" ]]; then
      echo '{"error": "Railway access token missing after refresh. Run: railway login"}'
      exit 1
    fi
  fi
fi

Documentation updates

Update the GraphQL helper docs to say the script authenticates in this order:

1. RAILWAY_API_TOKEN
2. ~/.railway/config.json:user.accessToken
3. ~/.railway/config.json:user.token

Also update AGENTS.md / CLAUDE.md, which currently say the token location is only user.token.

It may also be worth documenting that railway whoami can work while older helper scripts fail if they only check the legacy user.token key.

Reproduction

Using Railway CLI 4.42.1:

railway whoami --json

Succeeds.

Check config shape without printing secrets:

jq -r 'paths(scalars) | join(".")' ~/.railway/config.json | sort

Observed relevant keys:

user.accessToken
user.refreshToken
user.tokenExpiresAt

Run helper:

plugins/railway/skills/use-railway/scripts/railway-api.sh \
  'query { me { name email } }'

Observed:

{"error": "No Railway token found. Run: railway login"}

Impact

This breaks all skill workflows that fall back to the GraphQL helper, including metrics queries and other operations not exposed by the CLI, even though the Railway CLI itself is authenticated.

Note

This is not a request to expose or print tokens. The helper should continue to avoid logging secrets.

[ruiyuwg]

This remains reproducible with Railway CLI 5.26.2, but the current helper's scope is broader than the original access-token fallback.

Railway's Public API contract distinguishes token types:

• account/workspace/OAuth tokens use Authorization: Bearer <token>;
• project tokens use Project-Access-Token: <token>.

The helper currently ignores both documented noninteractive inputs (RAILWAY_API_TOKEN and RAILWAY_TOKEN) and unconditionally sends Bearer after reading the retired user.token field. That makes project-token automation impossible even when a valid RAILWAY_TOKEN is supplied.

Suggested update to the fix contract:

1. Prefer explicit credentials without reading local config: accept RAILWAY_API_TOKEN as Bearer and RAILWAY_TOKEN as Project-Access-Token; reject both being set simultaneously with a redacted, actionable error.
2. For browser-login compatibility, retain a non-refreshing fallback that reads only the current access token (with legacy-token compatibility if retained). Do not read user.refreshToken or invoke railway whoami from the helper: Railway CLI owns OAuth rotation, and a helper-side refresh would compete with that lifecycle.
3. If a stored access token is expired, fail predictably with setup guidance; direct callers to CLI/MCP when those routes expose the operation.
4. Keep credentials out of output, diagnostics, and avoidable curl argument vectors.
5. Update the GraphQL helper documentation and align the helper's embedded skill version with the released plugin version.

Credential-free regression coverage should execute the script against fixture config plus a fake HTTP client and cover OAuth/access-token, legacy-token (if kept), explicit account/workspace token, explicit project token, missing credentials, mutually-exclusive tokens, and expired access-token behavior. No live token or GraphQL request is needed.

References: Railway's Public API authentication docs and CLI authentication docs. The current upstream helper still has this behavior at main as of 2026-07-18.

[ruiyuwg]

Implemented the documented token-type/header selection, non-refreshing OAuth fallback, argv-safe header transport, version/docs alignment, and credential-free regression coverage in #63.