> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/sdks/install.md).

# Install a Norbix SDK

Install a Norbix SDK, get a key and set your credentials once.

Norbix has one SDK per language. They all work the same way: install the package, set your key and project id **once** as environment variables, and create a client with no arguments — the client reads the environment for you.

Every command and every line of code on this page was run on 2026-10-06 against a Norbix installation, with the package version shown in the table.

{% hint style="info" %}
Prefer the terminal? The [Norbix CLI](/codemash/cli/cli.md) calls the same API. Every page of the SDK reference also has a CLI tab.
{% endhint %}

## Pick your language

| Language                | Package                                                                                                                                               | Version | Install                                                                               | Quick start                                                        |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| JavaScript / TypeScript | [`@norbix.ai/ts`](https://www.npmjs.com/package/@norbix.ai/ts) (npm)                                                                                  | 4.13.0  | `npm install @norbix.ai/ts`                                                           | [JavaScript / TypeScript](/codemash/sdks/javascript-typescript.md) |
| Python                  | [`norbix`](https://pypi.org/project/norbix/) (PyPI)                                                                                                   | 3.12.0  | `pip install norbix`                                                                  | [Python](/codemash/sdks/python.md)                                 |
| .NET                    | [`Norbix.Api`](https://www.nuget.org/packages/Norbix.Api) (data) or [`Norbix.Hub`](https://www.nuget.org/packages/Norbix.Hub) (configuration) (NuGet) | 3.11.0  | `dotnet add package Norbix.Api`                                                       | [.NET](/codemash/sdks/net.md)                                      |
| Go                      | [`github.com/norbix-code/sdk-go/v2`](https://pkg.go.dev/github.com/norbix-code/sdk-go/v2)                                                             | v2.14.0 | `go get github.com/norbix-code/sdk-go/v2`                                             | [Go](/codemash/sdks/go-lang.md)                                    |
| Dart / Flutter          | [`norbix`](https://pub.dev/packages/norbix) (pub.dev)                                                                                                 | 2.10.0  | `dart pub add norbix`                                                                 | [Dart / Flutter](/codemash/sdks/flutter.md)                        |
| Swift                   | [`sdk-swift`](https://github.com/norbix-code/sdk-swift) (Swift Package Manager), libraries `NorbixApi` and `NorbixHub`                                | 1.8.0   | see [Swift](/codemash/sdks/swift.md)                                                  | [Swift](/codemash/sdks/swift.md)                                   |
| Kotlin / Java           | [`ai.norbix:norbix-kotlin`](https://central.sonatype.com/artifact/ai.norbix/norbix-kotlin) (Maven Central)                                            | 1.9.0   | `implementation("ai.norbix:norbix-kotlin:1.9.0")`                                     | [Kotlin](/codemash/sdks/kotlin.md)                                 |
| React + Redux Toolkit   | [`@norbix.ai/react-redux`](https://www.npmjs.com/package/@norbix.ai/react-redux) (npm)                                                                | 1.8.2   | `npm install @norbix.ai/react-redux @norbix.ai/ts @reduxjs/toolkit react-redux react` | [React Redux](/codemash/sdks/react-redux.md)                       |

The source code of each SDK is on GitHub: [sdk-ts](https://github.com/norbix-code/sdk-ts) · [sdk-python](https://github.com/norbix-code/sdk-python) · [sdk-net](https://github.com/norbix-code/sdk-net) · [sdk-go](https://github.com/norbix-code/sdk-go) · [sdk-dart](https://github.com/norbix-code/sdk-dart) · [sdk-swift](https://github.com/norbix-code/sdk-swift) · [sdk-kotlin](https://github.com/norbix-code/sdk-kotlin) · [react-redux](https://github.com/norbix-code/react-redux).

### Two parts of the API

Norbix answers on two hosts. Most SDKs give you a client for each:

| Host    | Address on the managed service | What it is for                                                      |
| ------- | ------------------------------ | ------------------------------------------------------------------- |
| **Api** | `https://api.norbix.ai`        | your app's data: records, files, users, sign-in                     |
| **Hub** | `https://hub.norbix.ai`        | configuration: schemas, integrations, templates, campaigns, account |

The quick starts use the **Api** part: they write and read records.

## Get a key

Code proves who it is with an **AI service user key** (`nbsu_…`). An AI service user belongs to your account and gets **roles** — the same roles a person gets: a project role (for example **Data Editor**, which reads and writes records) or an account role. The key can do what its roles allow, and nothing more. The key is shown **once**; Norbix keeps only a hash of it.

{% hint style="warning" %}
Cloud shows your AI service users and lets you remove them (**Account → AI service users**), but it cannot create one yet. Create it through the Hub API as shown below.
{% endhint %}

Run these three calls once (on your own installation, use your Hub address instead of `https://hub.norbix.ai`):

```sh
# 1. sign in with your Norbix account — the answer has a bearerToken
curl -s -X POST https://hub.norbix.ai/v3/auth \
  -H 'Content-Type: application/json' \
  -d '{"provider":"credentials","userName":"you@example.com","password":"<your password>"}'

# 2. list the roles of your project — copy the viewId of "Data Editor"
curl -s https://hub.norbix.ai/v3/membership/roles \
  -H "Authorization: Bearer <bearerToken>" \
  -H "norbix-project-id: pr_6JMU7afJi9tZQwfo6de4qq"

# 3. create the service user with that role — the answer has the key
curl -s -X POST https://hub.norbix.ai/v3/account/ai/service-users \
  -H "Authorization: Bearer <bearerToken>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Bookshop app",
       "projectRoles":[{"projectId":"pr_6JMU7afJi9tZQwfo6de4qq",
                        "roleIds":["pr_6JMU7afJi9tZQwfo6de4qq_nr_3ItSzVryuoXel0XG1hOYkx"]}]}'
```

Step 2 answers with the project's roles (`Administrator`, `Viewer`, `Data Editor`, `Developer`, …), each with a `viewId` like `pr_6JMU7afJi9tZQwfo6de4qq_nr_3ItSzVryuoXel0XG1hOYkx`. Step 3 answers:

```json
{
  "id": "aisu_3svT6JHiMKy3QVvD5sq5BN",
  "keyId": "aisk_4xPhAIHImWUssdrITp9nVt",
  "key": "nbsu_…",
  "responseStatus": { "isSuccess": true, "errors": [] }
}
```

Copy `key` now. Keep it in a secret store or an environment variable — never in your app's source code and never in a public web page. Pick the role that fits: **Viewer** reads but cannot write (an insert fails with *Caller is missing required permission 'database:create …'*); **Data Editor** reads and writes records. More about keys and environments: [Keys and environments](/codemash/get-started/keys-and-environments.md).

## Set your credentials

Set these environment variables once — in your shell, your hosting settings, or a `.env` file that your app loads. The SDKs do not read `.env` files themselves.

```sh
export NORBIX_API_KEY='nbsu_…'
export NORBIX_PROJECT_ID='pr_6JMU7afJi9tZQwfo6de4qq'
```

| Variable                            | What it is                                                                              | When you need it                                                                        |
| ----------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `NORBIX_API_KEY`                    | your AI service user key (`nbsu_…`)                                                     | always (or `NORBIX_BEARER_TOKEN`)                                                       |
| `NORBIX_PROJECT_ID`                 | the project the calls run against (`pr_…`), shown in Cloud → Project → Settings → Brand | always (Dart does not read it — see below)                                              |
| `NORBIX_BEARER_TOKEN`               | a signed-in user's token, used instead of a key                                         | when the code acts as one user                                                          |
| `NORBIX_ENV`                        | the project environment; `PROD` when not set                                            | to work in `TEST` or another environment                                                |
| `NORBIX_API_URL` · `NORBIX_HUB_URL` | your own Api and Hub addresses, for example `https://api.example.com`                   | only when you run Norbix yourself ([self-hosted](/codemash/get-started/self-hosted.md)) |

{% hint style="warning" %}
**Dart / Flutter reads other names.** `NorbixApi.fromEnv()` reads `NORBIX_API_KEY` and `NORBIX_API_BASE_URL` (not `NORBIX_API_URL`); `NorbixHub.fromEnv()` reads `NORBIX_HUB_API_KEY` and `NORBIX_HUB_BASE_URL`. The Dart SDK has no project id setting: it works with a key whose roles reach **one** project, like the key above. See [Dart / Flutter](/codemash/sdks/flutter.md).
{% endhint %}

## Create the client

With the variables set, the client needs no arguments. These are the first lines of each quick start:

{% tabs %}
{% tab title="JavaScript / TypeScript" %}

```js
import { Norbix, NorbixError } from '@norbix.ai/ts';

// Reads NORBIX_API_KEY and NORBIX_PROJECT_ID from the environment.
const norbix = new Norbix();
```

{% endtab %}

{% tab title="Python" %}

```python
from norbix_python import Norbix, NorbixError

# Reads NORBIX_API_KEY and NORBIX_PROJECT_ID from the environment.
norbix = Norbix()
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using Norbix.Sdk;
using Norbix.Sdk.Types.Api;

// Reads NORBIX_API_KEY and NORBIX_PROJECT_ID from the environment.
using var client = new NorbixClient();
```

{% endtab %}

{% tab title="Go" %}

```go
// Reads NORBIX_API_KEY and NORBIX_PROJECT_ID from the environment.
c, err := norbix.New(norbix.Options{})
if err != nil {
	log.Fatal(err)
}
defer c.Close()
```

{% endtab %}

{% tab title="Dart / Flutter" %}

```dart
import 'package:norbix/norbix_api.dart';

// Reads NORBIX_API_KEY (and NORBIX_API_BASE_URL, NORBIX_API_VERSION) from the environment.
final api = NorbixApi.fromEnv();
```

{% endtab %}

{% tab title="Swift" %}

```swift
import NorbixApi
import NorbixCore // NorbixError lives here

// Reads NORBIX_API_KEY and NORBIX_PROJECT_ID from the environment.
let client = try NorbixApiClient()
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
import ai.norbix.sdk.api.NorbixApi
import ai.norbix.sdk.core.NorbixError

// Reads NORBIX_API_KEY and NORBIX_PROJECT_ID from the environment.
NorbixApi().use { api ->
    // your calls
}
```

{% endtab %}
{% endtabs %}

React Redux builds on the JavaScript / TypeScript client. A web page has no environment variables, so there you pass the values in code — see [React Redux](/codemash/sdks/react-redux.md).

## Pass values in code

You do not have to use environment variables. Every client also takes the values in code — useful when one app talks to several projects. Anything you leave out still comes from the environment variables above.

{% tabs %}
{% tab title="JavaScript / TypeScript" %}

```js
const norbix = new Norbix({ apiKey: 'nbsu_…', projectId: 'pr_6JMU7afJi9tZQwfo6de4qq' });
```

{% endtab %}

{% tab title="Python" %}

```python
norbix = Norbix(api_key="nbsu_…", project_id="pr_6JMU7afJi9tZQwfo6de4qq")
```

{% endtab %}

{% tab title=".NET" %}

```csharp
using var client = new NorbixClient(new NorbixClientOptions
{
    ApiKey = "nbsu_…",
    ProjectId = "pr_6JMU7afJi9tZQwfo6de4qq",
});
```

{% endtab %}

{% tab title="Go" %}

```go
c, err := norbix.New(norbix.Options{APIKey: "nbsu_…", ProjectID: "pr_6JMU7afJi9tZQwfo6de4qq"})
```

{% endtab %}

{% tab title="Dart / Flutter" %}

```dart
final api = NorbixApi(
  config: NorbixConfig(baseUrl: 'https://api.norbix.ai', apiKey: 'nbsu_…'),
);
```

{% endtab %}

{% tab title="Swift" %}

```swift
let client = try NorbixApiClient(projectId: "pr_6JMU7afJi9tZQwfo6de4qq", apiKey: "nbsu_…")
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val api = NorbixApi(apiKey = "nbsu_…", projectId = "pr_6JMU7afJi9tZQwfo6de4qq")
```

{% endtab %}
{% endtabs %}

## Next steps

* Follow the quick start of your language: it writes a record, reads the records back and handles an error, with the output you should see.
* The quick starts use a `books` collection. Create it in Cloud first, as in step 3 of the [Quickstart](/codemash/get-started/managed-service/quickstart.md).
* Every operation of every module, with a tab per language, is in the SDK reference — for example [Insert Record](/codemash/sdks/database/collections/insert-record.md).