Hep.gg

Tokens and security

Token formats and lifetimes, verifying ID and access tokens against the JWKS, refresh-token rotation with reuse detection, and revoking access.

This page covers what Sign in with Hep.gg issues, how to verify it, and how to revoke it. Everything here is standard OpenID Connect, served by the hep.gg API on the hep.gg apex.

Token format and lifetimes

Both the id_token and access_token are RS256 JWTs signed with the keys published at the JWKS endpoint below.

Claims
iss
stringoptional
Always https://hep.gg.
aud
stringoptional
Your client_id.
sub
stringoptional
The stable Hep.gg user ID.
  • Access token TTL: 3600 seconds (1 hour) by default.
  • Refresh token TTL: 2592000 seconds (30 days) by default.
  • Authorization code: single-use, 60-second lifetime.

Access and refresh TTLs are configurable per registered app, so read the values from the token response rather than hard-coding them.

Discovery and keys

GEThttps://hep.gg/.well-known/openid-configurationPublic
OIDC discovery document: endpoint URLs, supported scopes, signing algorithms.
GEThttps://hep.gg/.well-known/jwks.jsonPublic
JSON Web Key Set used to verify token signatures.

Point your OIDC library at the discovery URL and it will find everything else, including the JWKS.

Verifying tokens

Validate every token before trusting it:

  1. Verify the RS256 signature against a key from /.well-known/jwks.json.
  2. Check iss is https://hep.gg and aud is your client_id.
  3. Check exp (not expired) and nbf/iat as usual.

Most OIDC client libraries do all of this for you when configured with the discovery URL. Keys rotate, so fetch and cache the JWKS (respecting cache headers) rather than pinning a single key.

Refresh tokens

Exchange a refresh token at the token endpoint with grant_type=refresh_token to get a fresh access token.

Revoking access

POSThttps://hep.gg/api/v1/login/oauth/revokeAuth required
Revoke an access or refresh token.

Send the token to revoke as token (client-authenticated, per RFC 7009). Use this on sign-out to proactively invalidate the user's tokens.

GEThttps://hep.gg/api/v1/login/oauth/end-sessionPublic
OIDC RP-initiated logout.

Redirect the user here to end their session. Pass id_token_hint and, if your app is configured with post-logout redirect URIs, post_logout_redirect_uri.