Users & Auth API

Manage user authentication, profiles, roles, and permissions.

Integration Patterns

Before diving into the raw API, check out the Authentication Integration Guide for complete flows:

• Registration & Login: Email/password and OAuth (Google)
• Token Management: Guest, authenticated, and server tokens
• Protected Routes: SSR and CSR auth patterns
• Profile Management: Update user info with correct field names

Quick Integration Example

import { createArkySDK } from 'arky-sdk';

const sdk = createArkySDK({
  baseUrl: 'https://api.arky.io',
  businessId: 'your-business-id',
  autoGuest: true,
  getToken: () => JSON.parse(localStorage.getItem('arky_token') || 'null'),
  setToken: (token) => localStorage.setItem('arky_token', JSON.stringify(token)),
  logout: () => localStorage.removeItem('arky_token'),
});

// Register
const { user, token } = await sdk.user.register({
  email: 'user@example.com',
  password: 'SecurePass123!',
  firstName: 'John',
  lastName: 'Doe',
});

// Get profile
const me = await sdk.user.me();

// Update profile (note: phoneNumbers is an array)
await sdk.user.updateUser({
  id: me.id,
  firstName: 'Jane',
  phoneNumbers: ['+1234567890'], // Array, not singular phoneNumber
});

See Authentication Guide for complete patterns.

---

Base URL

All User endpoints are prefixed with /v1/users.

Authentication Methods

Arky supports multiple authentication providers:

• EMAIL: Email + password with confirmation flow
• GOOGLE: OAuth2 via Google
• GUEST: Phone number-based guest tokens
• API: API keys for server-to-server

---

Register

Create a new user account with email and password.

Endpoint: POST /v1/users/register

SDKHTTP

const result = await sdk.user.registerUser({
  provider: 'EMAIL_REGISTER',
  email: 'user@example.com',
  password: 'SecureP@ssw0rd',
  reserveDomain: 'https://myapp.com', // For confirmation email link
});
// Confirmation email sent to user

Response:

{
  "success": true
}

Process:

1. Password is hashed with SHA256
2. User created with is_confirmed: false
3. Confirmation email sent with JWT token (valid 1 hour)
4. User must click link to activate account

Errors:

• 400: Email already exists
• 422: Validation failed (weak password, invalid email)

---

Confirm Email

Activate user account after registration.

Endpoint: PUT /v1/users/confirm

SDKHTTP

await sdk.user.confirmUser({
  token: 'JWT_TOKEN_FROM_EMAIL',
});
// Account now active, user can login

---

Login

Email Login

Endpoint: POST /v1/users/login

SDKHTTP

const auth = await sdk.user.loginUser({
  provider: 'EMAIL',
  email: 'user@example.com',
  password: 'SecureP@ssw0rd',
});

console.log('Access token:', auth.access_token);
console.log('Refresh token:', auth.refresh_token);
console.log('Expires at:', auth.expires_at);

Response:

{
  "userId": "user_abc123",
  "provider": "EMAIL",
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "tokenType": "Token",
  "expiresAt": 1698765432,
  "scope": "Fake",
  "isGuest": false
}

Errors:

• 422: Invalid email or password
• 422: Email not confirmed
• 400: Validation failed

Google OAuth Login

Step 1: Get Login URL

Endpoint: GET /v1/users/login/url

SDKHTTP

const { url } = await sdk.user.getLoginUrl({
  provider: 'GOOGLE',
  originUrl: 'https://myapp.com',
  redirectUrl: 'https://myapp.com/auth/callback',
});

// Redirect user to Google login
window.location.href = url;

Step 2: Exchange Code for Tokens

After Google redirects back with code:

SDKHTTP

const auth = await sdk.user.loginUser({
  provider: 'GOOGLE',
  code: 'GOOGLE_AUTH_CODE',
  originUrl: 'https://myapp.com',
});

Note: If the user’s email doesn’t exist, a new user is automatically created with is_confirmed: true.

Guest Login

Create a guest account using phone number.

SDKHTTP

const auth = await sdk.user.loginUser({
  provider: 'GUEST',
  phoneNumber: '+1234567890',
});

// Returns token with is_guest: true

---

Refresh Token

Obtain a new access token using a refresh token.

Endpoint: POST /v1/users/refresh (inferred)

SDKHTTP

// SDK handles refresh automatically, but you can manually call:
const newAuth = await sdk.user.refreshAccessToken({
  provider: 'GOOGLE',
  refreshToken: 'CURRENT_REFRESH_TOKEN',
});

Note: Refresh tokens for EMAIL and GOOGLE have no expiry (exp: None). Access tokens expire in 3600 seconds (1 hour).

---

Logout

Revoke OAuth tokens (Google only).

Endpoint: POST /v1/users/logout

SDKHTTP

await sdk.user.logout({
  provider: 'GOOGLE',
  token: 'ACCESS_TOKEN',
  originUrl: 'https://myapp.com',
});

---

Get Current User

Fetch authenticated user profile.

Endpoint: GET /v1/users/me

Headers: Authorization: Bearer <access_token>

SDKHTTP

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

console.log('User ID:', user.id);
console.log('Email:', user.email);
console.log('Roles:', user.roles);
console.log('Business configs:', user.business_user_configs);

Response:

{
  "id": "user_abc123",
  "name": "John Doe",
  "email": "john@example.com",
  "isConfirmed": true,
  "phoneNumbers": ["+1234567890"],
  "addresses": [],
  "roleIds": ["role_xyz"],
  "roles": [
    {
      "id": "role_xyz",
      "name": "Admin",
      "permissions": [...]
    }
  ],
  "apiTokens": [
    {
      "id": "token_123",
      "name": "My API Key",
      "value": "••••••••",
      "provider": "API"
    }
  ],
  "businessUserConfigs": [
    {
      "businessId": "biz_123",
      "settings": {}
    }
  ],
  "lifecycle": {
    "lastLoginAt": 1698765432,
    "onboardingCompleted": true
  }
}

---

Update Profile

Endpoint: PUT /v1/users/update

Headers: Authorization: Bearer <access_token>

SDKHTTP

const updated = await sdk.user.updateUser({
  name: 'Jane Smith',
  phoneNumbers: ['+1234567890'], // Array of phone numbers
  addresses: [
    {
      street: '123 Main St',
      city: 'New York',
      state: 'NY',
      zip: '10001',
      country: 'US',
    },
  ],
});

Verify Phone Code

Endpoint: POST /v1/users/phone-number/confirm

SDKHTTP

await sdk.user.phoneNumberConfirm({
  phoneNumber: '+1234567890',
  code: '123456',
});

---

Password Management

Forgot Password

Send password reset email.

Endpoint: POST /v1/users/forgot-password

SDKHTTP

await sdk.user.forgotPassword({
  email: 'user@example.com',
  reserveDomain: 'https://myapp.com',
});
// Reset link sent to email

Reset Password (with token)

Endpoint: POST /v1/users/reset-forgot-password

SDKHTTP

await sdk.user.resetForgotPassword({
  token: 'RESET_TOKEN_FROM_EMAIL',
  password: 'NewSecureP@ssw0rd',
});

Change Password (authenticated)

Endpoint: POST /v1/users/reset-password

Headers: Authorization: Bearer <access_token>

SDKHTTP

await sdk.user.resetPassword({
  oldPassword: 'OldP@ssw0rd',
  newPassword: 'NewSecureP@ssw0rd',
});

---

User Search

Search users within a business (requires ADMIN permission).

Endpoint: GET /v1/users/search

Headers: Authorization: Bearer <access_token>

SDKHTTP

const { items, cursor } = await sdk.user.searchUsers({
  query: 'john',
  businessId: 'biz_123',
  roleIds: ['role_admin'],
  limit: 20,
});

---

Roles Management

Assign Role

Assign a role to a user (requires ADMIN permission on business).

Endpoint: PUT /v1/users/set-role

Headers: Authorization: Bearer <access_token>

SDKHTTP

await sdk.user.setRole({
  userId: 'user_abc123',
  roleId: 'role_manager',
  businessId: 'biz_123',
});

---

API Tokens

Users can generate API tokens for server-to-server auth.

Generating a Token:

1. Call updateUser with apiTokens array:

SDKHTTP

await sdk.user.updateUser({
  name: user.name,
  apiTokens: [
    {
      id: 'token_new',
      name: 'Production API Key',
      value: 'arky_live_...', // Generate securely
      provider: 'API',
    },
  ],
});

Using API Tokens:

curl -H "X-API-Key: arky_live_..." \
  https://api.arky.io/v1/businesses/YOUR_BUSINESS_ID

---

Error Responses

Common Error Codes

Code	Error	Description
400	BAD_REQUEST	Invalid provider or malformed request
401	UNAUTHENTICATED	Missing or invalid token
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	User not found or email not confirmed
422	VALIDATION_FAILED	Field validation errors

Error Response Format

{
  "error": "VALIDATION_FAILED",
  "message": "Validation errors occurred",
  "details": [
    {
      "field": "email",
      "error": "EMAIL_EXISTS",
      "message": "email exists"
    }
  ]
}

Validation Errors

• EMAIL_EXISTS: Email already registered
• PASSWORD_WRONG: Invalid credentials
• PASSWORD_REQUIRED: Password field missing
• NOT_CONFIRMED: Email not verified
• INVALID_ORIGIN_URI: OAuth origin not whitelisted
• INVALID_REDIRECT_URI: OAuth redirect not whitelisted

---

JWT Claims Structure

Access Token Claims:

{
  sub: "user_abc123",        // User ID
  email: "user@example.com", // Email (optional for guests)
  provider: "EMAIL",          // AUTH provider
  exp: 1698765432            // Expiry timestamp
}

Refresh Token Claims:

Same as access token, but exp is null (never expires).

---

Related

• Authentication Integration Guide - Complete auth flows and patterns
• E-commerce Integration - Checkout with authenticated users
• Reservations Integration - Book services as logged-in user