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.signInWithApple(identityToken: string): Promise<AuthResult>
Amba.auth.signInWithGoogle(idToken: string): Promise<AuthResult>
Amba.auth.linkAccount(provider: 'apple' | 'google', idToken: string): Promise<AuthResult>
Amba.auth.linkEmailPassword(email: string, password: string): Promise<User>
Amba.auth.linkSmsOtp(phone: string, code: string): Promise<User>
Amba.auth.linkEmailOtp(email: string, code: string): Promise<User>
Amba.auth.unlinkSmsOtp(): Promise<User>
Amba.auth.unlinkEmailOtp(): Promise<User>
Amba.auth.unlinkApple(): Promise<User>
Amba.auth.unlinkGoogle(): Promise<User>
Amba.auth.getCurrentIdentifiers(): Promise<LinkedIdentifier[]>
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;
 
// You usually don't need to sign in explicitly: the first authenticated call
// (e.g. reading XP or a collection) lazily establishes an anonymous session.
// Call signInAnonymously() only when you want to control exactly when the
// server-side anonymous user is created (it counts as a monthly active user).
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. From the login screen — your app posts an email and we send the code.
//    Always returns 200 — we don't surface "this email isn't registered"
//    to avoid leaking which addresses are users.
await Amba.auth.requestEmailOtp('alice@example.com');
 
// 2. The user reads the code from their email and types it into your UI.
//    The verify response shape matches /email/login: session_token, refresh_token, user.
const result = await Amba.auth.verifyEmailOtp('alice@example.com', '123456');
console.log(result.session_token, result.refresh_token, result.user);

# Raw HTTP (no SDK):
curl -X POST https://api.amba.dev/v1/client/auth/email-otp/request \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com"}'
 
curl -X POST https://api.amba.dev/v1/client/auth/email-otp/verify \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","code":"123456"}'

// 1. Request a code. Phone must be E.164.
await Amba.auth.requestSmsOtp('+15551234567');
 
// 2. The user reads the code from their SMS inbox and types it in.
const result = await Amba.auth.verifySmsOtp('+15551234567', '123456');
console.log(result.session_token, result.user);

curl -X POST https://api.amba.dev/v1/client/auth/sms-otp/request \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+15551234567"}'
 
curl -X POST https://api.amba.dev/v1/client/auth/sms-otp/verify \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+15551234567","code":"123456"}'

# Via the CLI / MCP
amba projects update --bundle-id com.example.myapp
 
# Or PATCH directly
curl -X PATCH https://api.amba.dev/v1/admin/projects/$PROJECT_ID \
  -H "Authorization: Bearer $DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bundle_id":"com.example.myapp"}'

// 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.signInWithApple(identityToken);

amba projects update --google-oauth-client-id 123456.apps.googleusercontent.com
 
# Or PATCH directly
curl -X PATCH https://api.amba.dev/v1/admin/projects/$PROJECT_ID \
  -H "Authorization: Bearer $DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"google_oauth_client_id":"123456.apps.googleusercontent.com"}'

const idToken = await googleAuth.signIn().then((r) => r.idToken);
const result = await Amba.auth.signInWithGoogle(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);

// Reuses the same /sms-otp/request you'd use for a fresh sign-in.
await Amba.auth.requestSmsOtp('+15551234567');
 
// On code receipt, call linkSmsOtp INSTEAD of verifySmsOtp.
// → existing session_token stays valid; same user_id; user.phone set, user.phone_verified = true.
const user = await Amba.auth.linkSmsOtp('+15551234567', '123456');

try {
  await Amba.auth.linkSmsOtp('+15551234567', '123456');
} catch (err) {
  if (err instanceof AmbaApiError && err.code === 'PHONE_ALREADY_LINKED') {
    const conflictingUserId = err.details?.conflicting_user_id;
    // Decide: switch to that identity via verifySmsOtp, or abort.
  }
}

await Amba.auth.requestEmailOtp('alice@example.com');
const user = await Amba.auth.linkEmailOtp('alice@example.com', '123456');
// Collision code: EMAIL_ALREADY_LINKED.

// User is anonymous; attach email + password. Same user_id, same session
// token (no rotation). user.email is set and email_verified = true — a
// password-protected link is the user's active declaration of ownership.
const user = await Amba.auth.linkEmailPassword('alice@example.com', 'correct horse battery staple');
 
// After linking, the user can sign in on a new device with the same credentials:
// await Amba.auth.signInWithEmail('alice@example.com', 'correct horse battery staple');

// What's already attached? Identifier values come back MASKED — raw
// values stay server-side.
const ids = await Amba.auth.getCurrentIdentifiers();
// [
//   { provider: 'sms_otp',   verified: true, identifier_masked: '+1***4567' },
//   { provider: 'email_otp', verified: true, identifier_masked: 'a***@example.com' },
//   { provider: 'apple',     verified: true, identifier_masked: null },
// ]
 
// Remove one. Refused with LAST_IDENTIFIER if it would orphan the
// account — link a replacement first, then unlink.
await Amba.auth.unlinkSmsOtp();
await Amba.auth.unlinkEmailOtp();
await Amba.auth.unlinkApple();
await Amba.auth.unlinkGoogle();

// 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 `googleIosClientId: '...'` passed to the Expo config plugin
    try {
      await Amba.signInWithGoogle();
    } catch (err) {
      /* ... */
    }
  };
 
  return (
    <>
      <Button title="Continue with Apple" onPress={handleApple} />
      <Button title="Continue with Google" onPress={handleGoogle} />
    </>
  );
}