Authentication & Account

Manage user authentication, sessions, and account profiles using the sdk.auth and sdk.account modules.

Authentication (sdk.auth)

Create Guest Session

Create a guest session for anonymous users.

const result = await sdk.auth.session();

console.log('Access token:', result.accessToken);
console.log('Refresh token:', result.refreshToken);

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": 1704067200
}

Sign In Anonymously

Sign in anonymously. This is idempotent - if already authenticated, returns current tokens. Otherwise creates a guest session.

// Safe to call multiple times - idempotent
const tokens = await sdk.auth.signInAnonymously();

// Check if user is a guest
const isGuest = await sdk.auth.isGuest();
console.log('Is guest:', isGuest);

Check Guest Status

Check if the current user is a guest (anonymous).

const isGuest = await sdk.auth.isGuest();

if (isGuest) {
  // Prompt user to sign up
  console.log('Please sign in to save your progress');
}

Guest emails follow the pattern [email protected].

Request Auth Code

Request a magic link code for email authentication.

await sdk.auth.code({
email: '[email protected]',
});

// User receives email with verification code

Verify Auth Code

Verify the code received via email. On success, tokens are automatically set.

const result = await sdk.auth.verify({
email: '[email protected]',
code: '123456',
});

// Tokens are automatically stored via setToken callback
console.log('Logged in:', result.accessToken);

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": 1704067200
}

Refresh Token

Refresh an expired access token.

const result = await sdk.auth.refresh({
refreshToken: 'eyJhbGciOiJIUzI1NiIs...',
});

console.log('New access token:', result.accessToken);

Business Authentication

For multi-tenant applications, authenticate users against a specific business.

Request Business Auth Code

await sdk.auth.businessCode('biz_abc123', {
email: '[email protected]',
});

// Customer receives email with code

Verify Business Auth Code

const result = await sdk.auth.businessVerify('biz_abc123', {
email: '[email protected]',
code: '123456',
});

// Tokens are automatically stored
console.log('Customer logged in');

Account Management (sdk.account)

Get Current User

Get the authenticated user’s profile.

const user = await sdk.account.getMe({});

console.log('User ID:', user.id);
console.log('Email:', user.email);
console.log('Phone numbers:', user.phoneNumbers);
console.log('Addresses:', user.addresses);

Response:

{
  "id": "acc_abc123",
  "email": "[email protected]",
  "phoneNumbers": ["+1234567890"],
  "addresses": [
    {
      "label": "Home",
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  ],
  "roles": [
    {
      "businessId": "biz_123",
      "role": "Admin",
      "permissions": []
    }
  ],
  "createdAt": 1704067200
}

Update Account

Update the current user’s profile.

await sdk.account.updateAccount({
phoneNumbers: ['+1234567890'],
addresses: [
  {
    label: 'Home',
    line1: '123 Main St',
    city: 'New York',
    state: 'NY',
    postalCode: '10001',
    country: 'US',
  }
],
});

Add Phone Number

Add and verify a phone number.

// Step 1: Request verification code
await sdk.account.addPhoneNumber({
  phoneNumber: '+1234567890',
});
// SMS sent with verification code

Confirm Phone Number

Confirm the phone number with the received code.

// Step 2: Confirm with code
await sdk.account.phoneNumberConfirm({
  phoneNumber: '+1234567890',
  code: '123456',
});

Search Accounts

Search for accounts (admin function).

const result = await sdk.account.searchAccounts({
  query: 'john',
  limit: 20,
});

result.items.forEach(account => {
  console.log(account.email, account.id);
});

Subscribe to Audience

Subscribe the current account to an audience or newsletter.

// Subscribe to a newsletter
await sdk.account.subscribe({
  identifier: 'weekly-newsletter',
});

// Subscribe to a paid audience
const result = await sdk.account.subscribe({
  identifier: 'premium-content',
  planId: 'plan_monthly',
  successUrl: 'https://yourapp.com/success',
  cancelUrl: 'https://yourapp.com/cancel',
});

Delete Account

Permanently delete the current user’s account.

await sdk.account.deleteAccount({});

Complete Auth Flow Example

import { createSdk } from '@arky/sdk';

// Initialize SDK with token management
const sdk = createSdk({
  businessId: 'biz_abc123',
  getToken: async () => {
    const stored = localStorage.getItem('arky_tokens');
    return stored ? JSON.parse(stored) : null;
  },
  setToken: async (tokens) => {
    if (tokens) {
      localStorage.setItem('arky_tokens', JSON.stringify(tokens));
    } else {
      localStorage.removeItem('arky_tokens');
    }
  },
});

// Check if user is logged in
async function checkAuth() {
  const isGuest = await sdk.auth.isGuest();

  if (isGuest) {
    // User not logged in, show login form
    return null;
  }

  // Get user profile
  return await sdk.account.getMe({});
}

// Login flow
async function login(email: string) {
  // Step 1: Request code
  await sdk.auth.businessCode('biz_abc123', { email });

  // Show code input to user...
}

async function verifyLogin(email: string, code: string) {
  // Step 2: Verify code
  await sdk.auth.businessVerify('biz_abc123', { email, code });

  // User is now logged in, tokens stored automatically
  return await sdk.account.getMe({});
}

// Logout
function logout() {
  localStorage.removeItem('arky_tokens');
}