Authentication & Account

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

Arky uses a magic-link email flow for admin/platform users. Request a code, verify it, and tokens are returned. Access tokens are short-lived (1 hour); refresh tokens last 7 days.

Authentication (sdk.auth)

Request Auth Code

Request a magic link code for email authentication.

await sdk.auth.code({
email: 'user@example.com',
});

// 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: 'user@example.com',
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: 'customer@example.com',
});

// Customer receives email with code

Verify Business Auth Code

const result = await sdk.auth.businessVerify('biz_abc123', {
email: 'customer@example.com',
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('Memberships:', user.memberships);

Response:

{
  "id": "acc_abc123",
  "email": "user@example.com",
  "memberships": [
    {
      "businessId": "biz_123",
      "role": "Admin",
      "joinedAt": 1704067200
    }
  ],
  "apiTokens": [
    { "id": "tok_1", "name": "CI", "createdAt": 1704067200, "expiresAt": null }
  ],
  "authTokens": [
    {
      "id": "auth_1",
      "createdAt": 1704067200,
      "lastUsedAt": 1704070000,
      "accessExpiresAt": 1704070800,
      "refreshExpiresAt": 1704672000,
      "isVerified": true,
      "userAgent": "Mozilla/5.0 ..."
    }
  ]
}

Update Account

Update the current user’s account. Currently supports managing API tokens.

const result = await sdk.account.updateAccount({
apiTokens: [
  { name: 'My API Key' }
],
});

// Returns newly created tokens
console.log(result.newlyCreatedTokens);

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);
});

Delete Account

Permanently delete the current user’s account.

await sdk.account.deleteAccount({});

Sessions & API Tokens

Each successful verify / businessVerify call issues a new AuthToken stored on the account. The getMe() response includes:

• authTokens — active session tokens (access/refresh pairs). Each may carry a userAgent string recorded when the session was created, so users can identify devices.
• apiTokens — long-lived API tokens created via updateAccount({ apiTokens }), used for server-to-server auth via the Authorization: Bearer header.

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');
    }
  },
});

// Login flow — step 1: request code
async function login(email: string) {
  await sdk.auth.businessCode('biz_abc123', { email });
  // Show code input to user...
}

// Step 2: verify code — tokens are automatically stored via setToken
async function verifyLogin(email: string, code: string) {
  await sdk.auth.businessVerify('biz_abc123', { email, code });
  return await sdk.account.getMe({});
}

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