> 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/api-reference/guides/authentication.md).

# Authentication

How a REST call says who is calling and which project it is for.

Every call (except a few public ones such as `/v3/echo`) carries two things: **a key** that says who is calling, and **the project id** that says which project the call is for.

## How Norbix models it

| What             | How to send it                                                            | Example                                |
| ---------------- | ------------------------------------------------------------------------- | -------------------------------------- |
| Key              | `Authorization: Bearer <key>` header                                      | `Authorization: Bearer nbsu_…`         |
| Key (other form) | `X-Api-Key: <key>` header — AI service user keys only, not from a browser | `X-Api-Key: nbsu_…`                    |
| Project          | `projectId` query parameter, or a `projectId` field in a JSON body        | `?projectId=pr_6JMU7afJi9tZQwfo6de4qq` |
| Environment      | see [Environments](/codemash/api-reference/guides/environments.md)        | `?env=PROD`                            |

### Which key

| Key                                | Get it                                                                                                          | Good for                                                                                          |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Sign-in token** (JWT)            | `POST /v3/auth` on the Hub with your email and password                                                         | Your own scripts and tests. It has your account's rights.                                         |
| **AI service user key** (`nbsu_…`) | Created once through the Hub — see [Keys and environments](/codemash/get-started/keys-and-environments.md#keys) | AI agents, servers, CI. Scoped to one project or the account, read or admin, TEST or TEST + PROD. |

Get a sign-in token (Hub):

```sh
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>"}'
```

The answer has `bearerToken` (send it as `Authorization: Bearer …`, on the Hub and on the Api), `refreshToken` and `userId`. The token expires; sign in again, or use the refresh token, when calls start to answer `401`.

### Read a record with a read-only key

```sh
curl -s "https://api.norbix.ai/v3/database/collections/books?projectId=pr_6JMU7afJi9tZQwfo6de4qq" \
  -H "Authorization: Bearer $NORBIX_API_KEY"
```

```json
{
  "list": {
    "items": [
      { "_id": "6ac4f3493961abee730d1648", "title": "The Hobbit", "pages": 310, "in_stock": true,
        "_meta": { "schemaVersion": 1, "createdOn": 1791292233585, "modifiedOn": 1791292233585 } }
    ],
    "hasMore": false,
    "hasPrevious": false
  },
  "responseStatus": { "isSuccess": true, "errors": [] }
}
```

### Write a record with a sign-in token

The project id goes into the JSON body. A record `document` is sent as a JSON **string**:

```sh
curl -s -X POST https://api.norbix.ai/v3/database/collections/books \
  -H "Authorization: Bearer $NORBIX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"pr_6JMU7afJi9tZQwfo6de4qq",
       "document":"{\"title\":\"Dune\",\"pages\":412,\"in_stock\":false}"}'
```

```json
{ "id": "6ac4f4ec3961abee730d1649", "responseStatus": { "isSuccess": true, "errors": [] } }
```

### When it goes wrong

| What you see                                                          | Why                                                                                                                                                              |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTTP `401`, empty body                                                | No key, an unknown key, or an expired token                                                                                                                      |
| `CM-ERRORS-PROPERTY-001` "Property ProjectId is required"             | The call has no `projectId` (query or body)                                                                                                                      |
| "Caller is missing required permission 'database:create on …'"        | A read-only key tried to write                                                                                                                                   |
| `CM-ERRORS-AI-SU-014` "This service user is pinned to one project…"   | A project key was used for another project                                                                                                                       |
| `CM-ERRORS-INTEGRATIONS-006` "There is no active default integration" | The environment of the call has no database integration, for example a new TEST environment (see [Environments](/codemash/api-reference/guides/environments.md)) |

{% hint style="info" %}
Instead of the `projectId` parameter you can send the header `norbix-project-id: pr_…` (or `nb-project-id`). The SDKs and the CLI send that header for you, so their requests do not repeat the project id.
{% endhint %}

## Where you use it

* [Base URLs](/codemash/api-reference/guides/base-urls.md) · [Environments](/codemash/api-reference/guides/environments.md) · [How to test](/codemash/api-reference/guides/how-to-test.md)
* [Keys and environments](/codemash/get-started/keys-and-environments.md) · [Read-only keys](/codemash/ai/developers/read-only-keys.md)
* SDK: [Install the SDK](/codemash/sdks/install.md) · CLI: [CLI](/codemash/cli/cli.md)