Authentication

Implement user authentication with email, OAuth, and guest access

Arky supports multiple authentication methods: email/password, OAuth providers (Google, Apple), and guest access.

Email Authentication

Register a New User

POST /v1/users/register
SDK: sdk.user.registerUser() 
const result = await sdk.user.registerUser({
  email: '[email protected]',
  password: 'securePassword123',
  provider: 'EMAIL',
  firstName: 'John',
  lastName: 'Doe'
});

if (result.ok) {
  // User registered, confirmation email sent
  console.log('Check your email to confirm your account');
}

Confirm Email

After registration, users receive a confirmation email with a token:

PUT /v1/users/confirm
SDK: sdk.user.confirmUser() 
// Token from email link: https://yourapp.com/confirm?token=xxx
const token = new URLSearchParams(window.location.search).get('token');

const result = await sdk.user.confirmUser({ token });

if (result.ok) {
  // User confirmed, now logged in
  window.location.href = '/dashboard';
}

Login

POST /v1/users/login
SDK: sdk.user.loginUser() 
const result = await sdk.user.loginUser({
  email: '[email protected]',
  password: 'securePassword123',
  provider: 'EMAIL'
});

if (result.ok) {
  // Token automatically stored via setToken callback
  const user = result.val;
  console.log(`Welcome back, ${user.firstName}!`);
}

OAuth Authentication

Get OAuth URL

GET /v1/users/login/url
SDK: sdk.user.getLoginUrl() 
// Redirect user to OAuth provider
const result = await sdk.user.getLoginUrl({
  provider: 'GOOGLE', // or 'APPLE'
  redirectUrl: 'https://yourapp.com/auth/callback'
});

if (result.ok) {
  window.location.href = result.val.url;
}

Handle OAuth Callback

// On callback page: /auth/callback?code=xxx
const code = new URLSearchParams(window.location.search).get('code');

const result = await sdk.user.loginUser({
  provider: 'GOOGLE',
  code: code
});

if (result.ok) {
  window.location.href = '/dashboard';
}

Guest Access

Allow users to browse and purchase without creating an account:

const result = await sdk.user.loginUser({
  provider: 'GUEST'
});

if (result.ok) {
  // Guest session created
  // Can be converted to full account later
}
Tip

Guest users can complete purchases and later convert their account by adding email/password credentials.

Password Management

Forgot Password

POST /v1/users/forgot-password
SDK: sdk.user.forgotPassword() 
await sdk.user.forgotPassword({
  email: '[email protected]'
});

// Reset email sent
POST /v1/users/reset-forgot-password
SDK: sdk.user.resetForgotPassword() 
// Token from reset email
const token = new URLSearchParams(window.location.search).get('token');

const result = await sdk.user.resetForgotPassword({
  token,
  newPassword: 'newSecurePassword456'
});

Change Password (Logged In)

POST /v1/users/reset-password
SDK: sdk.user.resetPassword() 
const result = await sdk.user.resetPassword({
  oldPassword: 'currentPassword',
  newPassword: 'newSecurePassword456'
});

Session Management

Get Current User

GET /v1/users/me
SDK: sdk.user.getMe() 
const result = await sdk.user.getMe({});

if (result.ok) {
  const user = result.val;
  console.log(user.email, user.firstName, user.lastName);
}

Logout

POST /v1/users/logout
SDK: sdk.user.logout() 
await sdk.user.logout({});

// Clear local state
localStorage.removeItem('arky_token');
window.location.href = '/';

Phone Verification

Add and verify a phone number for SMS notifications:

Add Phone Number

POST /v1/users/phone-number
SDK: sdk.user.addPhoneNumber() 
await sdk.user.addPhoneNumber({
  phoneNumber: '+1234567890'
});

// SMS with confirmation code sent

Confirm Phone Number

POST /v1/users/phone-number/confirm
SDK: sdk.user.phoneNumberConfirm() 
const result = await sdk.user.phoneNumberConfirm({
  code: '123456' // Code from SMS
});

Error Handling

const result = await sdk.user.loginUser({
  email: '[email protected]',
  password: 'wrongpassword',
  provider: 'EMAIL'
});

if (!result.ok) {
  const error = result.val;

  switch (error.error) {
    case 'INVALID_CREDENTIALS':
      showError('Invalid email or password');
      break;
    case 'USER_NOT_CONFIRMED':
      showError('Please confirm your email first');
      break;
    case 'USER_DISABLED':
      showError('This account has been disabled');
      break;
    default:
      showError('Login failed. Please try again.');
  }
}

Complete Auth Flow Example

// auth.ts
import { sdk } from './lib/arky';

export async function login(email: string, password: string) {
  const result = await sdk.user.loginUser({
    email,
    password,
    provider: 'EMAIL'
  });

  if (result.ok) {
    return { success: true, user: result.val };
  }

  return { success: false, error: result.val.message };
}

export async function register(data: {
  email: string;
  password: string;
  firstName: string;
  lastName: string;
}) {
  const result = await sdk.user.registerUser({
    ...data,
    provider: 'EMAIL'
  });

  if (result.ok) {
    return { success: true };
  }

  return { success: false, error: result.val.message };
}

export async function getCurrentUser() {
  const result = await sdk.user.getMe({});
  return result.ok ? result.val : null;
}

export async function logout() {
  await sdk.user.logout({});
  localStorage.removeItem('arky_token');
}

Next Steps