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.

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,
})

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)
}

Retrieving user information

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

• DB API reference for complete method signatures and parameters

• Types reference for Auth and Tokens type definitions

• Connecting to SurrealDB for connection protocols and their effect on authentication

• DEFINE ACCESS statement for configuring access methods

• Security best practices for token and session duration configuration