authenticate

The .authenticate() method for the SurrealDB Rust SDK authenticates the current connection with a JWT token.

Authenticates the current connection with a JWT token.

Method Syntax

db.authenticate(token)

Arguments

Argument	Description
`token`	The JWT authentication token.

Example usage

Note: the following example uses the ureq crate with the json feature to first send a request to the database's /signup endpoint which returns a token. The reqwest crate and others can be used here instead.

Alternatively, you could use a command like the following, copy the returned token, and paste it into the .authenticate() method.

curl -X POST -H "Accept: application/json" -d '{"ns":"main","db":"main","ac":"account","user":"info@surrealdb.com","pass":"123456"}' http://localhost:8000/signup

As the DEFINE ACCESS statement below shows, a token will remain valid by default for 15 minutes.

// Use the following statement to set up the access
//
// DEFINE ACCESS account ON DATABASE TYPE RECORD
// 	SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
// 	SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) )
// 	DURATION FOR TOKEN 15m, FOR SESSION 12h
// ;

// DEFINE TABLE cat SCHEMALESS
//     PERMISSIONS for select, update, delete, create
//     WHERE $auth.id;

use serde::{Deserialize, Serialize};
use std::fmt::Display;
use surrealdb::Surreal;
use surrealdb::engine::remote::ws::Ws;
use surrealdb_types::SurrealValue;

#[derive(Deserialize, SurrealValue)]
struct Response {
    token: String,
}

impl Display for Response {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.token)
    }
}

#[derive(Serialize)]
struct Signup {
    ns: String,
    db: String,
    ac: String,
    email: String,
    pass: String,
}

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let db = Surreal::new::<Ws>("127.0.0.1:8000").await?;
    let response_string = ureq::post("http://127.0.0.1:8000/signup")
        .header("Accept", "application/json")
        .send_json(Signup {
            ns: "main".to_string(),
            db: "main".to_string(),
            ac: "account".to_string(),
            email: "info@surrealdb.com".to_string(),
            pass: "123456".to_string(),
        })
        .unwrap()
        .into_body()
        .read_to_string()
        .unwrap();

    let response = serde_json::from_str::<Response>(&response_string).unwrap();

    // Not signed in, doesn't work
    println!("{:?}", db.query("CREATE cat;").await);
    db.authenticate(response.token).await?;
    // Now it works
    println!("{:?}", db.query("CREATE cat;").await?);

    Ok(())
}

Refreshing a session (`.refresh()`)

When the server issues a token that includes a refresh component, you can obtain a new access token without signing in again. Build the usual db.authenticate(token) future, then call .refresh(). The inner future runs the refresh command and returns a new Token. If the token has no refresh material, the SDK returns an error (Missing refresh token).

// Get a token from signin
let token = db.signin(credentials).await?;

// Later, refresh the token
let new_token = db.authenticate(token).refresh().await?;

This pairs with the access and refresh model configured via DEFINE ACCESS (token duration, refresh behaviour, and scope depend on your statement).

Arguments

Argument	Description
`token`	The JWT authentication token.

Example usage

Alternatively, you could use a command like the following, copy the returned token, and paste it into the .authenticate() method.

curl -X POST -H "Accept: application/json" -d '{"ns":"main","db":"main","ac":"account","user":"info@surrealdb.com","pass":"123456"}' http://localhost:8000/signup`

As the DEFINE ACCESS statement below shows, a token will remain valid by default for 15 minutes.

// Use the following statements to set up the access
//
// DEFINE ACCESS account ON DATABASE TYPE RECORD
// 	SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
// 	SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) )
// 	DURATION FOR TOKEN 15m, FOR SESSION 12h
// ;

// DEFINE TABLE cat SCHEMALESS
//     PERMISSIONS for select, update, delete, create
//     WHERE $auth.id;

use serde::Deserialize;
use std::fmt::Display;
use surrealdb::engine::remote::ws::Ws;
use surrealdb::Surreal;

#[derive(Deserialize)]
struct Response {
    token: String,
}

impl Display for Response {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.token)
    }
}

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let db = Surreal::new::<Ws>("127.0.0.1:8000").await?;
    let token = ureq::post("http://127.0.0.1:8000/signup")
        .set("Accept", "application/json")
        .send_json(ureq::json!({
            "ns": "main",
            "db": "main",
            "ac": "account",
            "email": "info@surrealdb.com",
            "pass": "123456"
        }))
        .unwrap()
        .into_json::<Response>()
        .unwrap()
        .to_string();

    // Not signed in, doesn't work
    dbg!(db.query("CREATE cat;").await?);
    db.authenticate(token).await?;
    // Now it works
    dbg!(db.query("CREATE cat;").await?);

    Ok(())
}

Arguments

Example usage

Refreshing a session (`.refresh()`)

See also

Arguments

Example usage

See also

authenticate

Arguments

Example usage

Refreshing a session (.refresh())

See also

Arguments

Example usage

See also

Refreshing a session (`.refresh()`)