---
title: "Getting Started"
description: "The ZeyOS JavaScript client provides a generated, dependency-light interface to the ZeyOS REST API. It works in both browser environments and Node.js 18+, with built-in support for OAuth 2.0, sessi..."
canonical_url: "https://www.zeyos.com/guide/javascript-client/getting-started"
markdown_url: "https://www.zeyos.com/ai/guide/guide/javascript-client/getting-started.md"
section: "guide"
authority: "guide"
language: "en"
source_repository: "zeyos/client"
source_path: "docs/02-javascript-client/01-getting-started.md"
source_revision: "465c2c7016f5028405c987b17704f3491a597857"
---

# Getting Started

The ZeyOS JavaScript client provides a generated, dependency-light interface to the ZeyOS REST API. It works in both browser environments and Node.js 18+, with built-in support for OAuth 2.0, session-based authentication, and automatic token refresh.

Use the JavaScript client when:

- the CLI resource registry is not enough
- you are building a browser UI or a server-side integration
- you need request-level control through `client.request()`
- you want access to the full generated API surface instead of the CLI's curated subset

## Installation

:::info ESM only
`@zeyos/client` is an ES module (ESM) package. Use `import` (or dynamic `import()`) to load it. CommonJS `require()` is not supported.
:::

The client is distributed as an ES module source package. If you are working inside this repository, import it directly from the source tree:

```js
import { createZeyosClient } from './src/index.js';
```

If you are consuming it from another project, install the package and import it by name:

```bash
npm install @zeyos/client
```

```js
import { createZeyosClient } from '@zeyos/client';
```

The client has zero runtime dependencies and relies only on the standard `fetch` API available in modern browsers and Node.js 18+.

## Creating a Client

The `createZeyosClient` factory function returns a frozen client object with generated API methods, OAuth 2.0 helpers, and low-level request capabilities.

```js
import { createZeyosClient } from '@zeyos/client';

const client = createZeyosClient({
  platform: 'https://cloud.zeyos.com/demo/',
  validate: true,
  auth: {
    mode: 'session',
    session: { enabled: true, credentials: 'include' },
  },
});

const tickets = await client.api.listTickets({ limit: 10 });
```

Keep `validate: true` in new code. It checks generated methods and known-operation `client.request()` calls against the bundled schema before anything is sent, and throws `ZeyosValidationError` with a correction hint. It is off by default for compatibility.

### Custom Fields Belong to One Instance

Custom `extdata` keys differ between ZeyOS instances, so the bundled schema cannot know them. With validation on, naming an individual key requires a reviewed `customFields` contract for that instance:

```js
const client = createZeyosClient({
  platform: 'https://cloud.zeyos.com/demo/',
  validate: true,
  customFields: {
    accounts: { region: { type: 'string', enum: ['EMEA', 'APAC'] } }, // Reviewed keys for this instance
    tickets: {},                                                      // Known to have none
  },
});

client.schema.describe('accounts').customFields; // The definitions supplied above
```

The client does not fetch these definitions or check that they belong to the instance you are connected to. That is your responsibility: see [custom-field contracts](https://www.zeyos.com/guide/javascript-client/making-requests#custom-field-contracts) for binding a contract to its instance. Reading the whole collection with `extdata: 1` needs no contract.

The returned `client` object exposes:

- **`client.api`** -- Generated methods for all standard REST operations (e.g. `listTickets`, `createAccount`, `getTask`)
- **`client.oauth2`** -- OAuth 2.0 token operations and authorization URL helpers
- **`client.legacyAuth`** -- Legacy session authentication operations (`login`, `logout`, `verify`, `getUserInfo`)
- **`client.request()`** -- Low-level escape hatch for custom or advanced requests. A method and path call skips schema validation; see [Low-Level Requests](https://www.zeyos.com/guide/javascript-client/making-requests#low-level-requests)
- **`client.schema`** -- Runtime introspection and input validation (`describe`, `fields`, `resources`, `operations`, `validate`); see [Making Requests](https://www.zeyos.com/guide/javascript-client/making-requests#schema-introspection-and-validation)
- **`client.auth`** -- Token management (`getTokenSet`, `setTokenSet`, `clearTokenSet`)
- **`client.metadata`** -- Read-only info about the generated client (`generatedAt` timestamp, `services` array)

Alongside the `createZeyosClient` factory, the package exports a few named helpers and error types you can import directly:

```js
import {
  createZeyosClient,
  MemoryTokenStore,        // in-memory token store (or implement get()/set() yourself)
  ZeyosApiError,           // thrown on non-2xx responses
  ZeyosValidationError,    // thrown by pre-flight validation (validate: true)
  normalizeListResult,     // normalise a list response to { data, count? }
  normalizeCountResult,    // normalise a count response to a number
  normalizeTokenSet,       // normalise a raw token object to a TokenSet
  tokenResponseToTokenSet, // map an OAuth token response to a TokenSet
} from '@zeyos/client';
```

## Platform Configuration

The `platform` option tells the client where your ZeyOS instance lives. There are three ways to specify it:

### URL String

Pass the full URL to your ZeyOS instance. The client extracts the origin and instance name automatically.

```js
const client = createZeyosClient({
  platform: 'https://cloud.zeyos.com/demo/',
});
```

### Preset

Use a named preset for the ZeyOS cloud platform, combined with an `instance` name:

```js
const client = createZeyosClient({
  platform: 'live',
  instance: 'demo',
});
```

The `live` preset resolves to `https://cloud.zeyos.com`.

### Object

For full control, pass an object with `origin` and `instance`:

```js
const client = createZeyosClient({
  platform: {
    origin: 'https://cloud.zeyos.com',
    instance: 'demo',
  },
});
```

## Features

- **Zero dependencies** -- no external packages; only the standard `fetch` API is required
- **Browser + Node.js 18+** -- works in any environment with global `fetch`
- **Auto token refresh** -- transparently refreshes expired access tokens before requests or after bearer 401 responses
- **Generated API methods** -- the broader generated API surface is available as `client.api.<operationId>()`
- **Session + OAuth support** -- choose between cookie-based sessions, bearer tokens, or automatic fallback
- **Low-level escape hatch** -- `client.request()` for custom endpoints and advanced use cases

## Configuration Reference

| Option | Type | Description |
|--------|------|-------------|
| `platform` | `string \| { origin?: string, instance?: string, preset?: string, url?: string }` | ZeyOS instance URL, preset name (e.g. `'live'`), or object with `origin`/`instance` (and optionally `preset` or `url`) |
| `platform.origin` | `string` | Base origin URL (e.g. `'https://cloud.zeyos.com'`) |
| `platform.instance` | `string` | Instance name (e.g. `'demo'`) |
| `platform.preset` | `string` | Named preset (e.g. `'live'`) used when `origin` is omitted |
| `platform.url` | `string` | Full instance URL as an alternative to `origin`+`instance` |
| `instance` | `string` | Top-level instance name shortcut (used with preset-style `platform`) |
| `auth.mode` | `string` | Authentication mode: `'auto'` (default), `'oauth'`, `'session'`, or `'none'` |
| `auth.oauth.clientId` | `string` | OAuth 2.0 client ID for token operations |
| `auth.oauth.clientSecret` | `string` | OAuth 2.0 client secret for token operations |
| `auth.oauth.tokenStore` | `TokenStore` | Token storage backend (must implement `get()` and `set()`) |
| `auth.oauth.autoRefresh` | `boolean` | Automatically refresh access tokens before requests or after bearer 401 responses (default: `true`) |
| `auth.session.enabled` | `boolean` | Enable session-based authentication (default: `true`) |
| `auth.session.credentials` | `string` | Fetch credentials mode: `'include'`, `'same-origin'`, or `'omit'` |
| `auth.session.cookie` | `string \| () => string \| Promise<string>` | Explicit session cookie value or async function returning one (Node.js) |
| `headers` | `HeadersInit` | Default headers applied to every request |
| `fetch` | `typeof fetch` | Custom `fetch` implementation (defaults to `globalThis.fetch`) |
| `retry` | `{ maxRetries?: number, retryOn?: number[], baseDelayMs?: number, maxDelayMs?: number } \| false` | Retry policy. By default, up to two retries: `429` for any operation, `503` for reads only. Pass `false` to disable. See [Making Requests](https://www.zeyos.com/guide/javascript-client/making-requests#retries-and-rate-limiting) |
| `retryOnNetworkError` | `boolean` | Retry network errors, timeouts and `retryOn` statuses other than `429` for every operation (`true`) or none (`false`). Omit it to allow this for reads only |
| `timeoutMs` | `number` | Deadline for each attempt, in milliseconds. Default: none |
| `validate` | `boolean` | When `true`, validate each request against the schema before sending and throw `ZeyosValidationError` on problems (default: `false`). See [Making Requests](https://www.zeyos.com/guide/javascript-client/making-requests#schema-introspection-and-validation) |
| `customFields` | `Record<string, Record<string, { type?: string, enum?: Array<string \| number \| boolean>, description?: string }>>` | Reviewed custom-field keys per canonical resource, for one instance. See [custom-field contracts](https://www.zeyos.com/guide/javascript-client/making-requests#custom-field-contracts) |

## Next Steps

- **[Application Developers](https://www.zeyos.com/guide/tutorials/application-developers)** -- choose the browser or server-side integration path
- **[Authentication](https://www.zeyos.com/guide/javascript-client/authentication)** -- learn about session mode, OAuth 2.0 flows, and token management
- **[Making Requests](https://www.zeyos.com/guide/javascript-client/making-requests)** -- explore CRUD operations, filtering, sorting, pagination, and error handling
- **[Practical Guide](https://www.zeyos.com/guide/javascript-client/practical-guide)** -- real-world patterns and gotchas discovered during implementation
- **[Sample Application](https://www.zeyos.com/guide/sample-apps/kanban)** -- run the included Kanban board demo to see the client in action