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.
A root user has full access to the SurrealDB instance. Only username and password are required.
from surrealdb import Surreal
db = Surreal("ws://localhost:8000")
db.connect()
tokens = db.signin({
"username": "root",
"password": "root",
})
A namespace user has access to all databases within a specific namespace. Provide the namespace alongside credentials.
from surrealdb import Surreal
db = Surreal("ws://localhost:8000")
db.connect()
tokens = db.signin({
"namespace": "surrealdb",
"username": "tobie",
"password": "123456",
})
A database user has access to a single database. Provide both namespace and database alongside credentials.
from surrealdb import Surreal
db = Surreal("ws://localhost:8000")
db.connect()
tokens = db.signin({
"namespace": "surrealdb",
"database": "docs",
"username": "tobie",
"password": "123456",
})
A record access user authenticates against a DEFINE ACCESS method defined on a database. Provide namespace, database, access, and any variables required by the access definition.
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.
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.
Learn more
