Hydra
Docs

Understanding JWT scopes and what they grant access to.

API Keys & Scopes

Your JWT is a scoped API key — it only grants access to the streams you explicitly subscribed to when authenticating. Attempting to access a stream outside your scope returns 403 Forbidden.

JWT Structure

Your JWT payload contains:

{
  "sub": "0xYourWalletAddress",
  "streams": ["aircraft", "cyber", "alerts"],
  "tier": "advanced",
  "iat": 1710000000,
  "exp": 1710086400
}
Field Description
sub Your wallet address
streams List of stream IDs you can access
tier Your current token tier
iat Issued at (Unix timestamp)
exp Expires at (Unix timestamp)

Checking Your Scope

GET https://api.hydra.app/auth/me
Authorization: Bearer <your-jwt>

{
  "address": "0xYourWalletAddress",
  "streams": ["aircraft", "cyber"],
  "tier": "standard",
  "balance": 7200,
  "expiresAt": 1710086400,
  "rateLimit": {
    "requestsPerMinute": 300,
    "websocketConnections": 3
  }
}

Requesting Additional Streams

If you want to add streams mid-session, re-authenticate with the expanded list:

POST /auth/token
{
  "address": "0x...",
  "signature": "0x...",
  "streams": ["aircraft", "cyber", "alerts", "vessels"]
}

Your previous JWT is invalidated and a new one is issued with the updated scope.

⚠️
Warning

Requesting streams that require a higher token tier than you currently hold will silently exclude those streams from the issued JWT. Check the streams field in the response to confirm what you received.

Multiple Keys

You can hold multiple valid JWTs simultaneously — one per wallet. This is useful if you run multiple bots from different wallets, each with different stream subscriptions.

Invalidating a specific key is done via:

POST https://api.hydra.app/auth/revoke
Authorization: Bearer <jwt-to-revoke>