Authentication

End-user auth with anonymous sessions, Apple / Google social login, email-password, and account linking — all backed by Amba-native JWTs.

Amba provides a complete end-user auth system for mobile apps. Every user starts with an anonymous identity stored client-side; they can later sign in with Apple, Google, or email / password, and Amba preserves their anonymous history through account linking.

Credentials live in your project's database (physically isolated from every other Amba project) and passwords are hashed with bcrypt — no DIY crypto, no third-party auth vendor to get locked into.

How it works

On first launch, init() generates a local anonymous_id and persists it to storage.
When the user signs in (Apple, Google, or email), the SDK exchanges a credential for a session token (short-lived JWT) + refresh token (90 days). Both are persisted.
The SDK attaches Authorization: Bearer <session_token> to every user-scoped request.
When the session expires, the SDK rotates via POST /client/auth/refresh (rotating both tokens and revoking the old refresh token's server-side record).
logout() revokes the refresh token server-side and clears local state.

JWT claims

Session tokens carry:

Claim	Meaning
`sub`	`app_users.id`
`pid`	`projectId` — defense in depth: the API rejects a token that doesn't match the API key's project
`anon`	the original `anonymous_id`

Refresh tokens additionally carry a sid (session id) that maps to a server-side app_user_sessions row. Rotation revokes the old row and mints a new one, so a replayed refresh token is detected.

SDK usage

The @amba/client auth module signatures:

client.auth.getAnonymousId(): Promise<string>
client.auth.loginWithApple(identityToken: string): Promise<AuthResult>
client.auth.loginWithGoogle(idToken: string): Promise<AuthResult>
client.auth.signUpWithEmail(email: string, password: string): Promise<AuthResult>
client.auth.loginWithEmail(email: string, password: string): Promise<AuthResult>
client.auth.linkAccount(provider: 'apple' | 'google', token: string): Promise<AuthResult>
client.auth.getSession(): Promise<Session | null>
client.auth.refresh(): Promise<Session>
client.auth.me(): Promise<AppUser>
client.auth.logout(): Promise<void>
client.auth.onAuthStateChange(cb: (s: Session | null) => void): Unsubscribe

Anonymous identity (automatic)

import { Amba } from '@amba/client';
 
const client = Amba.configure({
  projectId: 'proj_xxx',
  apiKey: 'amb_dev_ck_xxx',
});
 
await client.init();
// Anonymous id is now persisted in storage
const anon = await client.auth.getAnonymousId();

// Sign up — creates a new app_users row + persists a session
const signup = await client.auth.signUpWithEmail(
  '[email protected]',
  'correct horse battery staple',
);
console.log(signup.user.id, signup.session_token, signup.refresh_token);
 
// Log in — verifies bcrypt, persists a session
const login = await client.auth.loginWithEmail('[email protected]', 'correct horse battery staple');

Passwords are hashed server-side with bcrypt at cost factor 10. The plaintext password is never stored and never returned to the client.

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

The server verifies the token's signature + issuer against Apple's JWKS before trusting any claims.

const idToken = await googleAuth.signIn().then((r) => r.idToken);
const result = await client.auth.loginWithGoogle(idToken);

Same JWKS verification on the server.

Account linking

Preserve a user's anonymous history when they later add a social login:

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

Email linking goes through the verified signUpWithEmail / loginWithEmail flow, not linkAccount.

Session management

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

Session shape:

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

Token refresh

The SDK persists refreshToken on persistSession(). Apps typically never call refresh manually — the API retries with exponential back-off, and a stale session token should be swapped for a refreshed one via POST /client/auth/refresh { refresh_token }.

If you need to force-rotate (e.g. after a permissions change on the server), call client.auth.refresh():

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

Current user

client.auth.me() fetches /client/users/me using the current session token and returns the AppUser record:

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

Common `AmbaApiError.code` values on auth

Code	When
`INVALID_CREDENTIALS`	Wrong email/password on `loginWithEmail`.
`USER_EXISTS`	Email already registered on `signUpWithEmail`.
`INVALID_EMAIL`	Malformed email.
`WEAK_PASSWORD`	Password doesn't meet policy.
`RATE_LIMITED`	Too many attempts from this IP / user.
`INVALID_TOKEN`	Apple/Google token failed signature verification.

Switch on err.code rather than err.message — messages are human-readable and may change.

Expo one-liners

@amba/expo wraps the native sign-in flows so you don't have to touch Apple / Google SDKs directly:

import { Amba } from '@amba/expo';
 
function LoginScreen() {
  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} />
    </>
  );
}

For email auth just use Amba.auth.signUpWithEmail(...) / Amba.auth.loginWithEmail(...) — the auth accessor is passed through to the underlying AmbaClient.

Routes reference

Method	Path	Description
`POST`	`/client/auth/anonymous`	Create a new anonymous user + session
`POST`	`/client/auth/social`	Exchange an Apple or Google identity token for an Amba session
`POST`	`/client/auth/email/signup`	Email signup (bcrypt-hashed password)
`POST`	`/client/auth/email/login`	Email login (verifies bcrypt hash)
`POST`	`/client/auth/link`	Link the current anonymous session to a social provider
`POST`	`/client/auth/refresh`	Rotate session + refresh tokens
`POST`	`/client/auth/logout`	Revoke the refresh token

All client auth routes require X-Api-Key. /link, /refresh, and /logout additionally require the current session / refresh token in the body.

Database tables

Table	Purpose
`app_users`	Core user record: `id`, `email`, `anonymous_id`, `display_name`, `auth_providers` (JSONB), `properties` (JSONB), `password_hash`, timestamps
`account_links`	Audit log of anonymous → authenticated transitions
`app_user_sessions`	Server-side refresh-token records. Each carries a sha256 hash of the refresh token, `expires_at`, `revoked_at`, `user_agent`, and `ip`

On this page