Skip to main content
JWT public key auth lets your end users call the Struct API using JWTs from their own auth provider, without exposing your sk_* API key client-side. See JWT Public Keys for how to create and manage keys.

​
Wire Format

Every request requires two credentials: your pk_jwt_* key (hardcoded in your app) and the user’s JWT (obtained at login).

​
REST

curl https://api.struct.to/v1/markets \
  -H "X-Api-Key: pk_jwt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
  -H "Authorization: Bearer <user_jwt>"

​
WebSocket

wss://api.struct.to/ws?api-key=pk_jwt_a1b2c3d4e5f6a1b2c3d4&token=<user_jwt>
Both parameters are required on every request.

​
Auth Flow

1

Request received

Request arrives with X-Api-Key: pk_jwt_xxx and Authorization: Bearer <user_jwt>.
2

Key lookup

The pk_jwt_ prefix triggers the JWT public key auth flow. The key record is loaded from the database (cached 60 seconds). If the key is disabled or not found, the request returns 401.
3

JWT verification

JWKS URL keys: The JWKS is fetched from the configured URL (cached 5 minutes). If the JWT’s kid is not found in the cached set, the JWKS is re-fetched once to handle key rotation.Inline public key: The PEM or JWK JSON key is used directly to verify the JWT signature.Supported algorithms: RS256, RS384, RS512, ES256, ES384, EdDSA.
4

Claims validation

aud and iss claims are validated if configured on the key. If the JWT is expired or the signature is invalid, the request returns 401.
5

Rate limiting and billing

The sub claim is extracted as the session identifier. The parent API key’s rate limit and credit cap apply. If per_session_rpm is set, an additional per-user rate limit is checked (keyed on pk_jwt_xxx:sub).
6

Request proceeds

Credits are billed through the parent API key.

​
Supported Algorithms

Only asymmetric JWT signing algorithms are supported:
FamilyAlgorithms
RSARS256, RS384, RS512
Elliptic CurveES256, ES384
Edwards CurveEdDSA
Symmetric algorithms (HS256, HS384, HS512) are not supported. JWTs signed with shared secrets will be rejected. Your auth provider must use asymmetric key pairs where the public key is exposed via a JWKS endpoint or provided inline.

​
Key Verification Methods

​
JWKS URL

Provide a JWKS endpoint URL and Struct will fetch the public keys automatically. This is the standard approach for most auth providers. The JWKS is cached for 5 minutes, and if a JWT arrives with an unknown kid, the JWKS is re-fetched once to handle key rotation.

​
Inline Public Key

Alternatively, provide the public key directly in PEM format (-----BEGIN PUBLIC KEY-----) or as JWK JSON ({"kty":"RSA", ...}). The key is used directly to verify JWT signatures without any external fetch.
Last modified on April 11, 2026