> 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/get-started/keys-and-environments.md).

# Keys and environments

The project id, the keys that let code call your project, and environments — what they are and where Cloud shows them.

Every call to Norbix — from the SDK, the CLI, an AI agent or plain REST — must say **which project** it is for, **who** is calling, and **which environment** of the project it works in. This page explains the three and shows where you find each one. It is the same for the managed service, self-hosted and enterprise installations.

## How Norbix models it

| Thing                     | Looks like                                             | What it is for                                                                | Where you find it                                                                                     |
| ------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Project id**            | `pr_6JMU7afJi9tZQwfo6de4qq`                            | Names the project. Not a secret.                                              | Cloud → Project → Settings → **Brand** → **Project Id** (copy button)                                 |
| **Sign-in token**         | a long JWT (JSON Web Token)                            | You, signed in with your email and password. Short-lived.                     | You get it when you sign in (Cloud, `norbix login`, `POST /v3/auth`)                                  |
| **AI service user key**   | `nbsu_…`                                               | A long-lived key for an AI agent, a script or a server. Can be **read-only**. | Shown **once**, when you create it — see below                                                        |
| **Environment**           | `PROD`, `TEST`, …                                      | A separate set of integrations and content inside one project.                | Cloud → Project → Settings → **Environments**                                                         |
| **Hub and API addresses** | `https://hub.norbix.ai/v3`, `https://api.norbix.ai/v3` | Where calls go.                                                               | Cloud → Project → Settings → **Access** → **Deployment endpoints**, and Account → **Connect your AI** |

Ids and their prefixes are explained in [Ids and prefixes](/codemash/get-started/ids.md).

### Project id

Open your project, then **Settings** → **Brand**. The **Project Id** row has a copy button.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-d50a90b3e3d668db86d916e32a5a246be5d7a242%2Fkeys-and-environments-1.png?alt=media" alt="Project Settings, Brand tab, the Project Id row with a copy button"><figcaption><p>Project Settings → Brand → Project Id.</p></figcaption></figure>

The project id is not a secret: it is in your app's code and in every request. On REST calls you send it as the `projectId` query parameter or the `norbix-project-id` header; the SDKs and the CLI send the header for you — see [Authentication](/codemash/api-reference/guides/authentication.md).

### Keys

There are two ways for code to prove who it is.

1. **Sign in** with your email and password. Cloud does this for you. The SDK has `norbix.login(...)`, and REST has `POST /v3/auth` (see [Authentication](/codemash/api-reference/guides/authentication.md)). The token has the rights of your own account — use it for your own scripts, not for servers.
2. **An AI service user key** (`nbsu_…`). An AI service user is an identity that belongs to your account and holds **Membership roles**, like a team member: project roles (Administrator, Developer, Data Editor, **Viewer**, or your own) and account roles (for example **Auditor**). The roles decide what the key may do. You can only give roles you hold yourself.

   The key is shown **once**. Norbix stores only a hash of it; if you lose it, issue a new one. A key with only the **Viewer** role is the safe choice for AI agents — see [Read-only keys](/codemash/ai/developers/read-only-keys.md).

{% hint style="warning" %}
Cloud has no screen that creates a key. **Account → AI service users** lists the service users your AI tools signed in as (through OAuth or `norbix login`) and removes them. Create a key through the Hub API as shown below. The **Regenerate API Key** button on a Membership "User as a service" user does nothing today, and the keys issued on the **Admin Portal** settings tab are only for the Admin portal.
{% endhint %}

Create a read-only key for one project (this was run against a test installation; replace the address with `https://hub.norbix.ai/v3` on the managed service):

```sh
# 1. sign in — 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. the id of the project's Viewer role (roles[].viewId where name is "Viewer")
curl -s "https://hub.norbix.ai/v3/membership/roles?projectId=pr_3dMEdKCg5DyxGuA4CtzS1F" \
  -H "Authorization: Bearer <bearerToken>"

# 3. create the service user with that role, and its first 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":"Report agent (read only)",
       "projectRoles":[{"projectId":"pr_3dMEdKCg5DyxGuA4CtzS1F",
                        "roleIds":["pr_3dMEdKCg5DyxGuA4CtzS1F_nr_1glnjkoPimR5r1stRHIRZp"]}]}'
```

The answer:

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

Copy `key` now and keep it in a secret store or an environment variable — never in your app's source code. The other routes for service users (list, issue a new key, revoke a key, delete) are under `/v3/account/ai/service-users` on the Hub. Until 2026-10-06 the body took a `scope` (`reach`, `rights`, `envs`); that body is now refused with `CM-ERRORS-AI-SU-016` (*Give the service user at least one role*).

### Environments

Every project starts with one environment, **PROD**. It cannot be deleted, and a request that names no environment uses it. You can add more — for example **TEST** — in **Settings** → **Environments** → **New environment**. Names are 1–15 upper-case letters, digits or spaces.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-71b95789c0b1b621208627ef1e69cec21ed74835%2Fkeys-and-environments-3.png?alt=media" alt="Project Settings, Environments tab with PROD marked current and a New environment button"><figcaption><p>Project Settings → Environments. A new project has only PROD.</p></figcaption></figure>

* Each environment has its own integrations, starting with its own database. Schemas, templates and triggers are kept per environment too, and **Promote** copies them up the ladder (for example TEST → PROD).
* When a project has more than one environment, a switch appears at the top of each module menu in Cloud.
* Trial accounts keep only PROD.
* A call with an AI service user key follows the same environment rule as a person's call. A tool call through the [MCP server](/codemash/ai/developers/mcp-server.md) works in **TEST** unless it names an environment, and a change in PROD must say `env: "PROD"` (see [Environments](/codemash/api-reference/guides/environments.md)).

More: [Projects and environments](/codemash/cloud/concepts/projects-and-environments.md).

### Addresses

**Settings** → **Access** → **Deployment endpoints** lists the API and Hub addresses of your project, each with a copy button. **Account → Connect your AI** shows the Hub, API and MCP addresses of the installation.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-8e65a831b5a74490870c161ded48554403e7b00a%2Fkeys-and-environments-2.png?alt=media" alt="Project Settings, Access tab with Deployment endpoints and the CORS section"><figcaption><p>Project Settings → Access → Deployment endpoints (here on a test installation).</p></figcaption></figure>

More: [Base URLs](/codemash/api-reference/guides/base-urls.md).

## Where you use it

* Cloud: [Project settings](/codemash/cloud/project/settings.md) · [Licences](/codemash/cloud/account/licences.md)
* SDK: [Install the SDK](/codemash/sdks/install.md) · CLI: [CLI](/codemash/cli/cli.md) · API: [Authentication](/codemash/api-reference/guides/authentication.md), [Environments](/codemash/api-reference/guides/environments.md)
* AI: [Read-only keys](/codemash/ai/developers/read-only-keys.md)