Authentication
The Go SDK supports signing in at different access levels, signing up record users, and managing authentication tokens. Authentication is required before most operations and determines what data the connection can access.
This page covers the different authentication levels, how to use refresh tokens, and how to manage authentication state on a connection.
API References
Authentication levels
SurrealDB supports four authentication levels. The fields you provide in the authentication data determine which level is used.
| Level | Required fields | Access to |
|---|
| Root | Username, Password | All namespaces and databases |
| Namespace | Namespace, Username, Password | All databases in the namespace |
| Database | Namespace, Database, Username, Password | A single database |
| Record | Namespace, Database, Access, Username, Password | Records determined by the access method |
You can provide credentials using either the Auth struct or a map[string]any.
Signing in as a system user
To sign in as a root, namespace, or database user, provide the appropriate fields. The level is determined by which fields are set.
token, err := db.SignIn(ctx, surrealdb.Auth{
Username: "root",
Password: "root",
})
token, err := db.SignIn(ctx, surrealdb.Auth{
Namespace: "my_ns",
Database: "my_db",
Username: "db_user",
Password: "db_pass",
})
Signing in as a record user
Record-level authentication requires the Access field, which specifies which DEFINE ACCESS method to use.
token, err := db.SignIn(ctx, surrealdb.Auth{
Namespace: "my_ns",
Database: "my_db",
Access: "user_access",
Username: "tobie",
Password: "s3cret",
})
You can also use a map[string]any to pass additional fields required by the access method:
token, err := db.SignIn(ctx, map[string]any{
"NS": "my_ns",
"DB": "my_db",
"AC": "user_access",
"user": "tobie",
"pass": "s3cret",
})
Signing up new record users
The .SignUp() method creates a new record user using a DEFINE ACCESS ... TYPE RECORD access method. The access method must be defined before calling .SignUp().
token, err := db.SignUp(ctx, map[string]any{
"NS": "my_ns",
"DB": "my_db",
"AC": "user_access",
"user": "new_user",
"pass": "s3cret",
"email": "user@example.com",
})
Using refresh tokens
SurrealDB v3 supports refresh tokens for TYPE RECORD access methods that have WITH REFRESH enabled. Use .SignInWithRefresh() or .SignUpWithRefresh() to receive both an access token and a refresh token.
tokens, err := db.SignInWithRefresh(ctx, map[string]any{
"NS": "my_ns",
"DB": "my_db",
"AC": "user_access",
"user": "tobie",
"pass": "s3cret",
})
The returned Tokens contains an Access field (JWT) and a Refresh field. To obtain new tokens without re-entering credentials, pass the refresh token:
newTokens, err := db.SignInWithRefresh(ctx, map[string]any{
"NS": "my_ns",
"DB": "my_db",
"AC": "user_access",
"refresh": tokens.Refresh,
})
Refresh tokens are only available with TYPE RECORD access methods that have WITH REFRESH enabled (SurrealDB v3+).
Using bearer access
For TYPE BEARER access methods (SurrealDB v3+), use the key parameter with a bearer key obtained from ACCESS ... GRANT. No username or password is required.
token, err := db.SignIn(ctx, map[string]any{
"NS": "my_ns",
"DB": "my_db",
"AC": "bearer_api",
"key": bearerKey,
})
Authenticating with an existing token
Use .Authenticate() to apply a previously obtained JWT to the connection. This is useful when restoring a session from a stored token or transferring authentication to a new connection.
if err := db.Authenticate(ctx, token); err != nil {
log.Fatal(err)
}
Invalidating authentication
Call .Invalidate() to remove the current authentication from the connection. After calling this, the connection returns to an unauthenticated state.
if err := db.Invalidate(ctx); err != nil {
log.Fatal(err)
}
The .Info() method returns the record of the currently authenticated user. This is only available when signed in as a record user.
info, err := db.Info(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println(info)
Learn more
