Skip to main content

​
Authentication

The Legend API uses bearer token authentication. Every request must include a query key or JWT in the Authorization header.

​
Three auth methods

MethodBest forDuration
Query KeyProgrammatic access, CI/CD, SDKsUntil revoked
OAuth JWTCLI, MCP agents, browser-based flows30 days
OAuth (MCP)Claude Code, Cursor (remote MCP server)30 days

​
Query keys

Get a query key from dashboard.legend.xyz under Settings > API Keys: 
qk_abc123_8f2e9a7b4c1d6e3f5a0b
Treat it like a password — store it in environment variables or a secrets manager, never in source code.

​
OAuth login (CLI)

The legend-cli can authenticate via Google SSO: 
legend-cli login
This opens your browser, completes the OAuth flow, and saves a JWT (valid for 30 days) to your profile. All subsequent CLI and local MCP commands use this token automatically.

​
Making requests

Include your query key or JWT as a bearer token: 
curl https://prime-api.legend.xyz/accounts \
  -H "Authorization: Bearer $LEGEND_QUERY_KEY"

​
Two layers of auth

The Legend API separates API access from fund authorization:
LayerWhat it doesWho has it
Query keyAuthenticates API requests — read data, create accounts, create plansYour server
Signer keyAuthorizes on-chain transactions — earn, withdraw, transferYou or your end-user
Your query key lets you do everything except move funds. To execute a plan, the sub-account’s signer must produce an EIP-712 signature. The signer key — whether an EOA private key or a Turnkey-managed P256 key — is controlled by you or your end-user at your discretion. Legend never holds it. See Signer types for more on EOA vs Turnkey P256.

​
Key rotation

You can have multiple active query keys for the same Prime Account. To rotate:
  1. Create a new query key
  2. Update your application to use the new key
  3. Revoke the old key
Both keys work simultaneously until you revoke the old one — no downtime.

​
Security best practices

  • Store query keys in environment variables or a secrets manager
  • Use separate keys for production and development
  • Rotate keys periodically and immediately if compromised
  • Query keys grant access to all sub-accounts under your Prime Account — scope access at the application level if needed