> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuralfactory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Exchange an API key for a token, and see what each key permission opens.

Every API request is made on behalf of an API key. Your program trades the key's secret for a short-lived token, then sends that token on each call. The secret itself travels only on the exchange.

Keys are created and managed on the [API keys](https://docs.neuralfactory.ai/user-guide/admin/api-keys.md) page of the web app.

## Get a token

```bash theme={null}
curl -s -X POST https://api.neuralfactory.ai/apikeys/token \
  -H "Content-Type: application/json" \
  -d '{"key_secret": "<your secret>"}'
```

```json theme={null}
{
  "access_token": "eyJhbGciOi…",
  "token_type": "bearer",
  "expires_in": 86400,
  "key_name": "hr-helper-script"
}
```

| Field | Meaning |
| - | - |
| `access_token` | The token to send on every other request |
| `token_type` | Always `bearer` |
| `expires_in` | Seconds until the token expires: 86400, so 24 hours |
| `key_name` | The name of the key the token belongs to |

When the token expires, exchange the secret again. There is no refresh token.

## Send the token

Put the token in the `Authorization` header of every request:

```bash theme={null}
curl https://api.neuralfactory.ai/runs/$RUN_ID \
  -H "Authorization: Bearer $NF_TOKEN"
```

## When authentication fails

| Status and `detail` | Cause |
| - | - |
| `401` `Invalid API key credentials` (from `/apikeys/token`) | The secret is wrong, or the key was deleted |
| `401` `API key is inactive` (from `/apikeys/token`) | The key is turned off, or its creator can no longer act |
| `401` `Not authenticated` | The `Authorization` header is missing |
| `401` `Invalid token: …` | The token is malformed or has expired |
| `401` `Invalid authentication credentials` | The token was valid, but its key has since been turned off or deleted, or its creator can no longer act |

A key's creator can no longer act when their account was deactivated or deleted, or when they left the organization the key belongs to. Their keys stop issuing tokens, and tokens already issued stop working within seconds.

## Who may use API keys

* **Enterprise**: Admins create and manage keys.
* **SaaS**: keys are part of the **Pro** and **Business** plans. Members create and see their own keys; on **Business** an Admin sees every key of the organization. On the **Free** plan, creating a key and every call made with one answer `403` with `API keys are not available on the Free plan. Upgrade your plan to use them.` A key made on a paid plan stops working if the account moves to **Free**.

## Permissions

A key reaches only what its permissions open. A call outside them answers `403` with `API key doesn't have required permissions: […]`. A key with **Admin** passes every permission check.

| Permission | Opens |
| - | - |
| **Chat** | `POST /chat`, the run endpoints (`/runs/…`, `/chats/{chat_id}/runs`), chat history and feedback, a chat's files and its browser view |
| **Search** | Knowledge search (`POST /search`) |
| **Agents** | Agents, workflows and workflow runs, workflow approvals, workflow schedules, the **Catalogue** |
| **Knowledge Base** | Knowledge bases and their sources, the list of toolkit types (`GET /toolkits/types`) |
| **Documents** | Documents in knowledge bases |
| **Skills** | Skills |
| **Users** | User administration. Only an Admin may give a key this |
| **Groups** | Group administration. Only an Admin may give a key this |
| **Admin** | Everything above, plus the endpoints that need an Admin: the organization's interactions (`GET /interactions` and the record pages), usage and billing reports. Only an Admin may give a key this |

Each operation in the Endpoints section names the permission it needs.

### What a key cannot do

Some endpoints are for signed-in people only and refuse a key:

| What | Answer to a key |
| - | - |
| Managing API keys, the **Tasks** list and the **Inbox**, the account's subscription and usage pages | `403` `This endpoint requires a signed-in user and cannot be accessed with an API key` |
| Agent schedules | `403` `Agent schedules are managed by signed-in users, not API keys` |
| Favourites | `403` `API keys cannot manage favourites` |
| Toolkit connections (a person's own sign-in to a service such as Outlook) | `401` `User authentication required` |
| Toolkits: listing, reading, creating, testing, changing, refreshing and deleting them | `401` `Authentication required`; for a named toolkit, `403` `You don't have access to this toolkit` or `Only admins can change this toolkit` |
| Duplicating a workflow | `403` `Duplicating requires a user principal` |

Workflow schedules are open to a key with **Agents**.

## What a key can reach

A key acts inside a scope:

* **Enterprise**: an organization's key reaches the agents and runs of that organization.
* **SaaS**: a key sees the agents and other resources that the person who created it sees. Runs are the exception: a key of a Business organization can read, stream and cancel every run of that organization, whoever started it.
* A key with no organization (one made on a SaaS personal account) reaches only what its creator made, and never the administration of users and groups, whatever its permissions.

A run outside the key's scope answers `403`.

## Who a key's work counts against

The runs a key starts count against the person who created it: their [limit of runs at the same time](https://docs.neuralfactory.ai/api-reference/rate-limits.md) and, on SaaS, their plan's usage. Setting `name` or `email` on `POST /chat` does not change that; those fields only label the turn in **Interactions**, where the key's work shows under the key's name.

## Related

* [API keys](https://docs.neuralfactory.ai/user-guide/admin/api-keys.md): create, turn off and delete keys in the web app
* [Your first API call](https://docs.neuralfactory.ai/api-reference/quickstart.md)
* [Errors](https://docs.neuralfactory.ai/api-reference/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.