Skip to main content

​
Authentication

The Prime API uses bearer token authentication. Every request must include your query key in the Authorization header.

​
Query keys

When your Prime Account is provisioned, you’ll receive a query key that looks like this: 
qk_abc123_8f2e9a7b4c1d6e3f5a0b
The prefix (qk_abc123) is the key’s public identifier. The full string is the secret — treat it like a password.

​
Making requests

Include your query key as a bearer token on every request: 
curl https://prime-api.legend.xyz/accounts \
  -H "Authorization: Bearer qk_abc123_8f2e9a7b4c1d6e3f5a0b" \
  -H "Content-Type: application/json"

​
Two layers of auth

The Prime API has two distinct authentication layers:
LayerWhat it doesWho has it
Query keyAuthenticates API requests (read data, create plans)Your server
Signer keyAuthorizes on-chain transactions (move funds)You or your end-user
Your query key lets you do everything except move funds. To actually execute a plan (earn, withdraw, transfer), the sub-account’s signer must produce an EIP-712 signature. This keeps the system non-custodial — Legend can never move funds without signer approval.

​
Error responses

If authentication fails, you’ll get one of these errors: 
// Missing header
{ "error": "missing_auth_header", "message": "Missing Authorization header" }

// Invalid key
{ "error": "invalid_api_key", "message": "Invalid API key" }

// Revoked key
{ "error": "api_key_revoked", "message": "API key has been revoked" }
All auth errors return HTTP 401.

​
Key rotation

You can have multiple active query keys for the same Prime Account. To rotate keys:
  1. Create a new query key (via the admin dashboard)
  2. Update your application to use the new key
  3. Revoke the old key
There’s no downtime — both keys work simultaneously until you revoke the old one.

​
Security best practices

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