Authentication & Account

Manage operator authentication, sessions, and platform accounts through sdk.account.

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.account.auth)

Request Auth Code

Request a magic link code for email authentication.

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

  // Keep challenge.challenge_id for the verify call.
  // The user receives the verification code by email.

Verify Auth Code

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

const result = await sdk.account.auth.verify({
  challenge_id: challenge.challenge_id,
  code: '123456',
});

// The browser SDK stores the issued session internally.
console.log('Logged in successfully');

Response:

{
	"id": "session_abc123",
	"access_token": "eyJhbGciOiJIUzI1NiIs...",
	"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
	"access_expires_at": 1704067200,
	"refresh_expires_at": 1704672000,
	"created_at": 1704063600,
	"is_verified": true
}

Refresh Token

Refresh an expired access token.

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

console.log('Access token refreshed successfully');

Store Authentication

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

Request Store Auth Code

const challenge = await sdk.account.auth.storeCode('store_abc123', {
  email: 'contact@example.com',
});

  // Keep challenge.challenge_id for the storeVerify call.

Verify Store Auth Code

const result = await sdk.account.auth.storeVerify('store_abc123', {
  challenge_id: challenge.challenge_id,
  code: '123456',
});

// The browser SDK stores the issued session internally.
console.log('Operator logged in');

Account Management (sdk.account)

Get Current User

Get the authenticated platform account.

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

console.log('User ID:', user.id);
console.log('Email:', user.email);

Response:

{
	"id": "acc_abc123",
	"email": "user@example.com",
	"lifecycle": {
		"last_login_at": 1704067200,
		"onboarding_completed": true
	}
}

Update Account

Update the current account. API tokens and sessions are separate resources and are not embedded in this command.

const result = await sdk.account.update({});
console.log(result.success);

Search Accounts

Search for accounts (admin function).

const result = await sdk.account.search({
	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.delete({});

Sessions

Each successful verify or storeVerify call creates a separate account session. Sessions are not embedded in Account.

List Sessions

const page = await sdk.account.session.list();
for (const session of page.items) {
	console.log(session.id, session.status, session.refresh_expires_at);
}

Revoke Session

await sdk.account.session.revoke("session_abc123");

API Tokens

API tokens are separate long-lived credentials for backend automation. Send their value through the Authorization: Bearer header.

List API Tokens

Create API Token

const created = await sdk.account.apiToken.create({
	name: "CI deployment",
	expires_at: null,
});

// `value` is returned at creation time; store it securely.
const secret = created.value;

Rename or Revoke API Token

await sdk.account.apiToken.update({
	id: "token_abc123",
	name: "CI deployment",
});
await sdk.account.apiToken.revoke("token_abc123");

Complete Auth Flow Example

import { createAdmin } from "arky-sdk/admin";

const sdk = createAdmin({
	baseUrl: "https://api.arky.io",
	storeId: "store_abc123",
	market: "us",
});

let pendingChallengeId: string | null = null;

async function requestLoginCode(email: string) {
	const challenge = await sdk.account.auth.storeCode("store_abc123", { email });
	pendingChallengeId = challenge.challenge_id;
}

async function verifyLogin(code: string) {
	if (!pendingChallengeId) throw new Error("Request a login code first");
	await sdk.account.auth.storeVerify("store_abc123", {
		challenge_id: pendingChallengeId,
		code,
	});
	pendingChallengeId = null;
	return sdk.account.getMe({});
}

await sdk.logout();