Authentication

curl -X PATCH '${BASE_URL}/client/users/me' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "display_name": "Alice" }'

curl -X POST '${BASE_URL}/client/auth/email/signup' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "alice@example.com", "password": "…", "display_name": "Alice" }'

Amba.auth.signInAnonymously(): Promise<AuthResult>
Amba.auth.signInWithEmail(email: string, password: string): Promise<AuthResult>
Amba.auth.signUpWithEmail(email: string, password: string): Promise<AuthResult>
Amba.auth.signInWithSocial(provider: 'apple' | 'google', idToken: string): Promise<AuthResult>
Amba.auth.linkAccount(provider: 'apple' | 'google', idToken: string): Promise<AuthResult>
Amba.auth.getSession(): Promise<Session | null>
Amba.auth.refresh(): Promise<Session>
Amba.auth.me(): Promise<AppUser>
Amba.auth.signOut(rotateAnonymousId?: boolean): Promise<void>
Amba.auth.onAuthStateChange(cb: (s: Session | null) => void): Unsubscribe

import { Amba } from '@layers/amba-web';
 
await Amba.configure({
  projectId: 'proj_xxx',
  clientKey: 'amba_ck_xxx',
});
 
// Anonymous id is persisted automatically after configure().
const anon = Amba.anonymousId;
 
// Mint a server-side anonymous session before the user creates an account.
await Amba.auth.signInAnonymously();

// Sign up — creates a new user and persists a session.
const signup = await Amba.auth.signUpWithEmail('alice@example.com', 'correct horse battery staple');
console.log(signup.user.id, signup.session_token, signup.refresh_token);
 
// Sign in — verifies the password and persists a session.
const login = await Amba.auth.signInWithEmail('alice@example.com', 'correct horse battery staple');

// 1. From the login screen — your app posts an email and we send the link.
//    Always returns 200 — we don't surface "this email isn't registered" to
//    avoid leaking which addresses are users.
await fetch(`${BASE_URL}/client/auth/magic-link/request`, {
  method: 'POST',
  headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'alice@example.com' }),
});
 
// 2. The user clicks the link `https://<your-origin>/auth/verify?token=<raw>`.
//    Your verify-page extracts the token from the URL and POSTs it back. The
//    response shape matches /email/login: session_token, refresh_token, user.
const res = await fetch(`${BASE_URL}/client/auth/magic-link/verify`, {
  method: 'POST',
  headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ token }),
});
const { data } = await res.json();
// data.session_token, data.refresh_token, data.user

// 1. Get an Apple identity token from the native flow.
//    In Expo, use the @layers/amba-expo helper below.
const identityToken = await appleAuth.signIn({ ... }).then(r => r.identityToken);
 
// 2. Exchange it for an Amba session.
const result = await Amba.auth.signInWithSocial('apple', identityToken);

const idToken = await googleAuth.signIn().then((r) => r.idToken);
const result = await Amba.auth.signInWithSocial('google', idToken);

// User is anonymous right now; link their Apple identity without creating
// a new user row.
await Amba.auth.linkAccount('apple', identityToken);
// or
await Amba.auth.linkAccount('google', idToken);

// Get current session (null if not signed in)
const session = await Amba.auth.getSession();
if (session) console.log('Signed in as', session.user.email);
 
// Listen for auth state changes
const unsubscribe = Amba.auth.onAuthStateChange((session) => {
  if (session) {
    console.log('Signed in:', session.user.id);
  } else {
    console.log('Signed out');
  }
});
// ...later
unsubscribe();
 
// Sign out — best-effort server revoke; always clears local state.
await Amba.auth.signOut();

interface Session {
  sessionToken: string;
  refreshToken: string;
  user: AppUser;
  expiresAt: string; // ISO-8601
}

const newSession = await Amba.auth.refresh();

const user = await Amba.auth.me();
console.log(user.email, user.display_name, user.properties);

import { Amba, AmbaApiError } from '@layers/amba-web';
 
try {
  await Amba.auth.signInWithEmail('alice@example.com', 'hunter2');
} catch (err) {
  if (err instanceof AmbaApiError) {
    if (err.code === 'INVALID_CREDENTIALS') {
      // Show "wrong email or password" copy.
    } else if (err.code === 'RATE_LIMITED') {
      // Back off and prompt the user to try again in a minute.
    } else {
      // Fall through to a generic error toast.
    }
  } else {
    // Non-Amba throw (network teardown, mid-flight JS error). Rare.
  }
}

import { Amba } from '@layers/amba-expo';
 
function SignInScreen() {
  const handleApple = async () => {
    try {
      await Amba.signInWithApple();
    } catch (err) {
      // User cancelled, or Apple Sign In not available on this device.
    }
  };
 
  const handleGoogle = async () => {
    // Requires `google: { clientId: '...' }` passed to Amba.init()
    try {
      await Amba.signInWithGoogle();
    } catch (err) {
      /* ... */
    }
  };
 
  return (
    <>
      <Button title="Continue with Apple" onPress={handleApple} />
      <Button title="Continue with Google" onPress={handleGoogle} />
    </>
  );
}