Cratopus icon
Launch Console

Authentication

This section covers how to integrate and use the supported authentication mechanisms in Crate.

Passkeys (WebAuthn)

Passkeys are the primary and recommended method for authentication in the Crate ecosystem.

Using the JS SDK

The easiest way to implement Passkeys in your frontend is using the CrateIdentityJS SDK. It wraps the standard navigator.credentials APIs and handles the multi-step begin and finish ceremonies for you.

To initialize the SDK:

const identity = new CrateIdentityJS.CrateIdentity({
  publishableKey: "YOUR_PUBLISHABLE_KEY",
  domain: "https://api.crate.cc" // or your Crate gateway domain
});

Registration (Creating a Passkey)

Call register with a unique identifier (like an email address) to create a new user account with a passkey.

try {
  const result = await identity.register("user@example.com");
  console.log("Registered successfully:", result);
} catch (error) {
  console.error("Failed to register:", error);
}

Behind the scenes, this calls the BeginRegistration and FinishRegistration endpoints on the Crate backend.

Login (Asserting a Passkey)

Call login with the user’s identifier to trigger the passkey prompt.

try {
  const result = await identity.login("user@example.com");
  console.log("Logged in successfully:", result);
} catch (error) {
  console.error("Failed to login:", error);
}

This automates the BeginLogin and FinishLogin endpoints.

Magic links act as a secure, passwordless fallback for users.

[!NOTE] Magic link generation is strictly a backend operation. Crate does not send emails or SMS messages natively.

Implementation Flow

  1. Generate the Token (Backend): Your application backend calls the /crate.v1.IdentityService/GenerateMagicLink REST API endpoint with the user’s identifier. Crate returns a secure token.
  2. Deliver the Token (Backend): Your backend dispatches an email or SMS containing the magic link (e.g., https://your-app.com/verify?token=XYZ) using your provider of choice (SendGrid, Twilio, etc.).
  3. Verify the Token (Backend or Frontend): When the user clicks the link, your system extracts the token and calls the /crate.v1.IdentityService/VerifyMagicLink API. If successful, Crate returns the IdentityId to complete the session.

Passwords

Traditional username and password authentication is fully supported for scenarios where you need a conventional login flow.

The REST API supports the following endpoints:

  • POST /v1/identity/register: Register a new user with an email and password.
  • POST /v1/identity/login: Authenticate using a username and password.
  • POST /v1/identity/reset-password: Request and execute a password reset flow.