SurrealDB can authenticate clients using JSON Web Tokens (JWTs). Your application or identity provider issues a signed JWT; SurrealDB verifies the signature and builds a session from the token’s claims so subsequent queries run with the correct identity and scope. The same mechanism applies whether the client connects over HTTP, WebSocket, or other supported interfaces: the token establishes who is calling before authorisation runs.
You register JWT-based access with DEFINE ACCESS … TYPE JWT (see DEFINE ACCESS). SurrealDB validates the token’s signature and standard claims (such as issuer and audience) according to your definition. Verification supports symmetric algorithms such as HS256 with a shared secret, and asymmetric algorithms such as RS256 and ES256 using a configured public key or JWKS—matching how major providers sign tokens at scale. Choose the model that matches your key management: shared secrets for internal services, public-key verification when keys are rotated by an external IdP.
A typical JWT access definition names:
The signing method (for example HS256 with a secret, or RS256/ES256 with a public key or JWKS URL).
Expected issuer and audience values so only tokens minted for your deployment are accepted.
How claim names map into session data (so
$authexposes fields yourPERMISSIONSrules can use).
Claims from the JWT are mapped into SurrealDB session variables (including $auth) so permissions and queries see a consistent view of the user whether authentication came from SurrealDB or from elsewhere. Typical mappings include subject, roles, and custom namespaces your application relies on for authorisation. The exact claim names depend on your issuer; configure the mapping in DEFINE ACCESS so your policies read stable fields regardless of whether the upstream token uses flat or nested JSON.
That design works well with third-party identity providers—Auth0, AWS Cognito, Okta, Azure AD, and similar systems that issue OIDC/OAuth2 JWTs. You configure issuer, audience, signing keys, and claim bindings once; users authenticate with the provider, receive a JWT, and present it to SurrealDB without storing end-user passwords in your database.
Keep token lifetimes and key rotation in mind: short-lived access tokens and explicit issuer/audience checks reduce the impact of a leaked JWT, and asymmetric verification lets SurrealDB trust keys published via JWKS when your provider rotates them.
When you need database-managed authentication (for example sign-up and credential checks implemented as part of your data model), use DEFINE ACCESS … TYPE RECORD. That path issues and validates access in coordination with records in your database while still producing a session compatible with the same permission model as JWT access. Many deployments combine both: system operators use root or scoped database users, end users authenticate via RECORD or brokered JWT access, and PERMISSIONS enforce row- and field-level rules for everyone.
In practice, teams often start with HS256 and a single secret for development or private networks, then move to RS256 or ES256 with JWKS in production so verification does not depend on long-lived shared secrets crossing service boundaries. The DEFINE ACCESS reference lists the exact clauses for each approach.
For how authentication fits the wider security model, read the authentication overview. For every option on JWT and record access, use the reference for DEFINE ACCESS.