---
title: TypeScript SDK
description: Install @hexelstudio/titan-sdk, authenticate with an access token
  or an API key, send the scope headers Titan reads, and handle its errors.
url: https://hexelstudio.com/docs/titan/sdk
---

`@hexelstudio/titan-sdk` is the TypeScript client for Titan. It has typed functions for every public Titan route, React Query hooks, and flow helpers that run a whole task (create a deployment, connect an account, edit a policy) in one call.

| Import | What it has |
| --- | --- |
| `@hexelstudio/titan-sdk` | The platform API: deployments, policy, tools, connections, approvals, the Agent Ledger. `configure`, `createTransport`, `TitanError`. |
| `@hexelstudio/titan-sdk/flows` | Flow helpers: `provisionDeployment`, `connectWithApiKey`, `startOAuth`, `editPolicy`, `allowInPolicy` and the policy builders. |
| `@hexelstudio/titan-sdk/react` | React Query v5 hooks for the platform API and the flows. |
| `@hexelstudio/titan-sdk/agent` | The agent API, for an agent process: identity exchange, capabilities, invocations, approvals. |

## Install

During the private preview, the package is published privately to GitHub Packages. Ask Hexel Studio at [support@mail.hexelstudio.com](mailto:support@mail.hexelstudio.com) for access, then point the `@hexelstudio` scope at GitHub Packages with a GitHub token that has the `read:packages` scope:

```ini .npmrc
@hexelstudio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```

```bash
npm install @hexelstudio/titan-sdk
```

The package is ESM. The React hooks need `react` 18 or 19 and `@tanstack/react-query` 5; both are optional peer dependencies.

<Note>
Use version 0.2.1 or later. In 0.2.0, `connectWithApiKey({ apiKey })` sent the key in a field that Titan stores but never hands to a tool, so the connection looked active but every tool call through it failed. Delete connections made that way and connect them again.
</Note>

## Base URL

Every path starts with `/titan/...`; the base URL carries the rest.

| Where | Base URL |
| --- | --- |
| Titan Cloud and management | `https://api.hexelstudio.com/v1` (the default) |
| A Titan Dedicated deployment | `https://api.hexelstudio.com/v1/cells/<enforcement deployment id>` |
| A deployment's own hostname: everything except management | `https://<enforcement deployment id>.titan.hexelstudio.com`, from `tenantBaseURL(id)` |

A request through a deployment's own hostname acts only for that deployment. Its agent API, registry, tools and administration (approvals, the Agent Ledger, sessions) are served there, and administration calls need no `Titan-Enforcement-Deployment` header: the hostname names the deployment. Management (deployments, policy) is not, so keep `https://api.hexelstudio.com/v1` for it.

## Authenticate

The platform API takes either an access token or an API key.

<Tabs>
  <Tab title="Access token (browser or server)">
    Send an access token issued by `https://sts.hexelstudio.com` for a member or a service user of your organization (see [Authenticate](https://hexelstudio.com/docs/identity/authenticate)). Never send an ID token from your sign-in provider.

    ```ts
    import { configure, listDeployments } from '@hexelstudio/titan-sdk';

    configure({
      baseURL: 'https://api.hexelstudio.com/v1',
      getAccessToken: async () => (await (await fetch('/auth/sts-token', { method: 'POST' })).json()).access_token,
      getContext: () => ({ organizationId, workspaceId, environmentId }),
    });

    const { data } = await listDeployments();
    ```

    `getAccessToken` is called before every request, so it can return a refreshed token. For a fixed token, pass `token` instead.
  </Tab>
  <Tab title="API key (server only)">
    A [service user's API key](https://hexelstudio.com/docs/identity/service-users#api-keys) is sent as `X-API-Key`; the edge exchanges it for an access token. Keep API keys on a server: never put one in browser code.

    ```ts
    import { configure, listDeployments } from '@hexelstudio/titan-sdk';

    configure({ baseURL: 'https://api.hexelstudio.com/v1', apiKey: process.env.HEXEL_API_KEY });
    const { data } = await listDeployments();
    ```
  </Tab>
</Tabs>

`configure()` sets the transport that every generated function and flow uses. A server that acts for several callers creates one transport per request instead:

```ts
import { createTransport } from '@hexelstudio/titan-sdk';

const request = createTransport({ baseURL: 'https://api.hexelstudio.com/v1', token: callerAccessToken });
const deployments = await request('/titan/management/deployments', { method: 'GET' });
```

Each operation needs a permission in your organization, for example `titan:enforcement_deployment:read` to read a deployment's policy and `titan:enforcement_deployment:create` to change it, or `titan:approval:decide` to decide an approval.

## Scope headers

The transport sends the context you give it as headers:

| Context field | Header | Sent on |
| --- | --- | --- |
| `organizationId` | `X-Organization-Id` | Every request, when set. It must match the organization of your token or key. |
| `workspaceId` | `X-Workspace-Id` | Every request, when set. The workspace the request acts in. |
| `environmentId` | `X-Environment-Id` | Every request, when set. Needs a workspace. |
| `enforcementDeploymentId` | `Titan-Enforcement-Deployment` | Only administration calls (`/titan/admin/...`: approvals, the Agent Ledger, sessions). |

Titan Cloud serves many organizations from one plane, so every administration call through `https://api.hexelstudio.com/v1` must name the deployment it acts on by its enforcement deployment id (`td-` and 32 hex characters). Without it, or naming another organization's deployment, the call is refused with `403`. Read the id from the deployment's policy (`enforcement_deployment_id` in `getDeploymentPolicy`).

```ts
configure({
  baseURL: 'https://api.hexelstudio.com/v1',
  apiKey: process.env.HEXEL_API_KEY,
  getContext: () => ({ organizationId, workspaceId, enforcementDeploymentId: 'td-0123456789abcdef0123456789abcdef' }),
});
```

A `Titan-Enforcement-Deployment` header you pass on a single call wins over the context. See [Request and response headers](https://hexelstudio.com/docs/identity/headers) for how the API checks them.

## Connect an account

`connectWithApiKey` connects an account for a toolkit with a static key, or with the named credential fields the toolkit's auth config declares:

```ts
import { connectWithApiKey } from '@hexelstudio/titan-sdk/flows';

const account = await connectWithApiKey({
  authConfigId,
  apiKey: process.env.ACME_API_KEY,
  account: { toolkit_slug: 'ACME_CRM', workspace_id: workspaceId },
});
```

The key is sent as `credentials.access_token`, the value Titan hands to the tool at call time. For an OAuth toolkit, use `startOAuth` and, on your redirect page, `completeOAuth(code, state)`.

To decide what agents may do with the connection, see [Policies and approvals](https://hexelstudio.com/docs/titan/policies-and-approvals).

## Errors

A generated function resolves with `{ data, status, headers }` for a `2xx` response and throws a `TitanError` for anything else. `TitanError` has the HTTP `status` and the parsed response `body`:

```ts
import { TitanError, decideApproval } from '@hexelstudio/titan-sdk';

try {
  await decideApproval({ id: approvalId }, { decision: 'approve' });
} catch (err) {
  if (!(err instanceof TitanError)) throw err;
  const code = (err.body as { error?: { code?: string } })?.error?.code;
  if (err.status === 409 && code === 'APPROVAL_NOT_PENDING') {
    // Someone else decided it, or it expired.
  } else if (err.status === 403 && code === 'NOT_AN_ELIGIBLE_APPROVER') {
    // This person is not in an approval role for the request.
  } else {
    throw err;
  }
}
```

Every Titan error body has the same shape, `{"error": {"code": "..."}}`, often with a `message`; branch on `status` and `error.code`, never on `message`. Agent API errors also carry `retryable` and a `request_id`. [Errors](https://hexelstudio.com/docs/api/errors) lists the codes.

The flow helpers throw the same `TitanError` when a step is refused. `provisionDeployment` throws a `ProvisioningError` (with the failed `operation`) when provisioning ends in `FAILED_CLOSED`.

### Retries

- Retry only what can be repeated safely: a `429`, a `503`, or an agent API error with `retryable: true`, after a back-off.
- Creating a deployment takes an `Idempotency-Key`; `provisionDeployment` sends a new one unless you pass `idempotencyKey`. Pass your own to make a retried create return the same deployment.
- An agent's side-effecting capability call needs an `Idempotency-Key` (`428 IDEMPOTENCY_KEY_REQUIRED` without one). Reuse the same key when you retry the same call.
