Authentication
Project keys for your services, and your own users' sign-in tokens for user-facing calls.
Every /v1 operation needs Authorization: Bearer <token>. There is no other header and no query
parameter. The health probes and /.well-known/jwks.json need no authentication.
Sparq accepts two kinds of token.
Sparq API keys
Project keys, service identities and operator keys look like sqk_ followed by 43 random
characters. They are shown once, when issued or rotated, and Sparq stores only a peppered HMAC of
the key and a short fingerprint you can match in logs.
Use keys from servers only. Never put a key in a browser or a mobile app: call Sparq from your own back end instead.
curl "$SPARQ_API_URL/v1/whoami" -H "Authorization: Bearer $SPARQ_KEY"Your users' sign-in tokens
For user-facing calls, send your user's own access token. Sparq verifies it against the issuer you
registered on the project (issuers[] on ProjectCreate):
| Check | Rule |
|---|---|
| Algorithm | RS256 or ES256 only. Symmetric algorithms are refused. |
| Key | The token header must carry a kid; keys come from the issuer's jwks_uri. |
| Claims | iss, aud, exp and sub are required; 30 seconds of clock skew is allowed. |
| Client | The claim named by tenant_claim must name a registered, active client, or the call is refused with 403. |
| Roles | Read from the claim named by roles_claim (default roles). |
Sparq never stores the user's subject. It derives a pseudonymous user id from the issuer and the subject.
Revocation
A revoked credential is refused within 30 seconds at most, with 401 credential_revoked.
Tokens Sparq gives your tools
When an agent calls one of your tools, Sparq does not forward the user's token. It mints a
delegated token: ES256, valid for at most five minutes, for one purpose, with an act claim
naming the agent. Verify it with the public keys at:
curl "$SPARQ_API_URL/.well-known/jwks.json"