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

​
Query keys

Get a query key from dashboard.legend.xyz under Settings > API Keys:
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:
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:

​
Two layers of auth

The Legend API separates API access from fund authorization: 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