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: '[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.access_token);

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1704067200
}

Refresh Token

Refresh an expired access token.

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

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

Store Authentication

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

Request Store Auth Code

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

// Profile receives email with code

Verify Store Auth Code

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

// Tokens are automatically stored
console.log('Profile 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": "[email protected]",
  "memberships": [
    {
      "store_id": "store_123",
      "role": "Admin",
      "joined_at": 1704067200
    }
  ],
  "api_tokens": [
    { "id": "tok_1", "name": "CI", "created_at": 1704067200, "expires_at": null }
  ],
  "auth_tokens": [
    {
      "id": "auth_1",
      "created_at": 1704067200,
      "last_used_at": 1704070000,
      "access_expires_at": 1704070800,
      "refresh_expires_at": 1704672000,
      "is_verified": true,
      "user_agent": "Mozilla/5.0 ..."
    }
  ]
}

Update Account

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

const result = await sdk.account.updateAccount({
api_tokens: [
  { 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 / storeVerify call issues a new AuthToken stored on the account. The getMe() response includes:

• auth_tokens — active session tokens (access/refresh pairs). Each may carry a user_agent string recorded when the session was created, so users can identify devices.
• api_tokens — long-lived API tokens created via updateAccount({ api_tokens }), 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({
  storeId: 'store_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.storeCode('store_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.storeVerify('store_abc123', { email, code });
  return await sdk.account.getMe({});
}

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