Authentication

The Python SDK supports signing in as a root, namespace, database, or record-level user. After signing in, the connection is authenticated for all subsequent operations until the session is invalidated or the connection is closed.

This page covers how to sign in, sign up, manage tokens, and inspect the current user.

API References

Signing in users

The .signin() method authenticates the connection. The fields you pass determine the authentication level. The method returns Tokens on success, which contain the JWT access token and optional refresh token.

Refer to the API reference for the full list of parameters at each level.

		from surrealdb import Surreal

		db = Surreal("ws://localhost:8000")
		db.connect()

		tokens = db.signin({
		    "username": "root",
		    "password": "root",
		})

		from surrealdb import Surreal

		db = Surreal("ws://localhost:8000")
		db.connect()

		tokens = db.signin({
		    "namespace": "surrealdb",
		    "username": "tobie",
		    "password": "123456",
		})

		from surrealdb import Surreal

		db = Surreal("ws://localhost:8000")
		db.connect()

		tokens = db.signin({
		    "namespace": "surrealdb",
		    "database": "docs",
		    "username": "tobie",
		    "password": "123456",
		})

		from surrealdb import Surreal

		db = Surreal("ws://localhost:8000")
		db.connect()

		tokens = db.signin({
		    "namespace": "surrealdb",
		    "database": "docs",
		    "access": "account",
		    "variables": {
		        "email": "info@surrealdb.com",
		        "password": "123456",
		    },
		})

All examples above use the synchronous API. The async variant works the same way — prefix each call with await.

Signing up users

The .signup() method registers a new record user through a record access method and returns Tokens. Signup is only available for record-level access.

You must provide the namespace, database, and access fields, along with any variables expected by the access definition.

		from surrealdb import Surreal

		db = Surreal("ws://localhost:8000")
		db.connect()

		tokens = db.signup({
		    "namespace": "surrealdb",
		    "database": "docs",
		    "access": "account",
		    "variables": {
		        "email": "newuser@surrealdb.com",
		        "password": "s3cureP@ss",
		    },
		})

		from surrealdb import AsyncSurreal

		db = AsyncSurreal("ws://localhost:8000")
		await db.connect()

		tokens = await db.signup({
		    "namespace": "surrealdb",
		    "database": "docs",
		    "access": "account",
		    "variables": {
		        "email": "newuser@surrealdb.com",
		        "password": "s3cureP@ss",
		    },
		})

Authenticating with an existing token

If you already have a JWT token — for example, one returned from a previous .signin() or stored in a cookie — you can authenticate the connection directly with .authenticate().

		db.authenticate("eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...")

		await db.authenticate("eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...")

This is useful in server-side applications where the token is passed from a client request and needs to be forwarded to the database connection.

Retrieving user information

The .info() method returns the record data for the currently authenticated record user. This is only available when signed in as a record-level user.

		user = db.info()
		print(user)

		user = await db.info()
		print(user)

The return value is a Value containing the fields of the authenticated user's record. If no record user is authenticated, the method returns None.

Signing out

The .invalidate() method clears the authentication state for the current connection. After invalidation, subsequent operations will execute as an unauthenticated user.

		db.invalidate()

		await db.invalidate()

Learn more

• Surreal API reference for complete method signatures and parameters

• Tokens type reference for the structure of the returned tokens

• Authentication in SurrealDB for an overview of authentication concepts

• DEFINE ACCESS for defining record and JWT access methods

• Connecting to SurrealDB for connection setup and protocol options