Authentication

SurrealDB supports several levels of authentication, from system users to fine-grained record access. Version 2 of the PHP SDK represents each level as a typed credential class, so the required fields are explicit.

API references

Credential types

Each authentication level has a credential class in the SurrealDB\SDK\Auth namespace.

Signing in users

The signin() method authenticates an existing user. Pass the credential class for the level you need. It returns a Tokens object holding the access token and an optional refresh token.

use SurrealDB\SDK\Auth\RootAuth;

$tokens = $db->signin(new RootAuth('root', 'surrealdb'));

The session is authenticated after a successful sign in.

Signing up users

The signup() method creates a new record user through a defined record access method. Use RecordAccessAuth with the variables your access definition expects.

use SurrealDB\SDK\Auth\RecordAccessAuth;

$tokens = $db->signup(new RecordAccessAuth(
    namespace: 'surrealdb',
    database: 'docs',
    access: 'account',
    variables: [
        'email' => 'info@surrealdb.com',
        'pass' => '123456',
    ],
));

Authenticating with a token

If you already have an access token, authenticate with it directly instead of signing in again. This restores a session without re-entering credentials.

$db->authenticate($accessToken);

Bearer access

A bearer access key authenticates against a defined bearer access method. Use BearerAuth with the access name and the key.

use SurrealDB\SDK\Auth\BearerAuth;

$tokens = $db->signin(new BearerAuth(
    namespace: 'surrealdb',
    database: 'docs',
    access: 'api',
    key: $bearerKey,
));

Refreshing and revoking tokens

When a record access method issues refresh tokens, signin() and signup() return a Tokens object with both an access and a refresh token. Use the refresh token to obtain a new pair without re-entering credentials. Both operations are on the ConnectionController.

$tokens = $db->connection()->refresh($tokens);   // new access + refresh pair

$db->connection()->revoke($tokens);              // invalidate the refresh token

By default the SDK renews an expiring token in the background. To sign the session out instead of renewing it, set invalidateOnExpiry to true on connect().

use SurrealDB\SDK\Connection\ConnectOptions;

$db->connect('ws://127.0.0.1:8000/rpc', new ConnectOptions(
    invalidateOnExpiry: true,
));

Providing credentials on connect

Rather than calling signin() separately, pass credentials to connect() through the authentication option. This is preferred for system users because it lets the SDK re-authenticate automatically after a reconnect.

use SurrealDB\SDK\Connection\ConnectOptions;
use SurrealDB\SDK\Auth\RootAuth;

$db->connect('ws://127.0.0.1:8000/rpc', new ConnectOptions(
    namespace: 'surrealdb',
    database: 'docs',
    authentication: new RootAuth('root', 'surrealdb'),
));

The authentication option also accepts a closure, which is useful when credentials are fetched at runtime.

$db->connect('ws://127.0.0.1:8000/rpc', new ConnectOptions(
    authentication: fn () => new RootAuth(getUsername(), getPassword()),
));

Listening to authentication changes

The SDK emits an auth event whenever the authentication state changes, including on sign in, sign up, token renewal, and invalidation. The payload is the current Tokens object, or null when signed out.

$db->subscribe('auth', function (?Tokens $tokens): void {
    echo $tokens === null ? 'Signed out' : 'Authenticated';
});

Selecting the current user

The auth() builder compiles to SELECT * FROM ONLY $auth, which returns the record of the authenticated record user.

$me = $db->auth()->execute();

Signing out

The invalidate() method clears the session's authentication. Queries after this run unauthenticated.

$db->invalidate();

Learn more

• Surreal API reference for the authentication method signatures

• Authentication in SurrealDB for how authentication works at the database level

• DEFINE ACCESS for defining access methods