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

# API keys

> Create and manage API keys. A new key is tied to one workspace and one environment.

An **API key** (`eng_...`) is the credential for servers, scripts, CI and AI agents. [Authentication](/developers/get-started/authentication) shows how to send one; this page is about the keys themselves: which workspace and environment they belong to, how to create and find them, and what the API answers when a key goes out of bounds.

## A key belongs to one workspace and one environment

Every new key is created for **one workspace and one environment** of your account - for example your Finance workspace in Production - and works only there. Keys created before keys were tied to a workspace and an environment are the exception: see **Full account access** [below](#find-rename-and-delete-keys).

* Requests made with the key run in that workspace and environment. Nothing in the request can point a key at a different one.
* Resources in another workspace or environment are invisible to the key: lists leave them out, and fetching one by id answers `404`, exactly as if the id did not exist. Shared catalogs, such as the list of applications, are the same everywhere.
* Create **one key per environment** an integration uses. A Staging key cannot touch Production.

## Create a key

1. Sign in at [app.engini.io](https://app.engini.io).
2. Switch to the workspace and environment the key is for, using the switcher in the left navigation bar. With one workspace and only Production there is nothing to switch.
3. Open **API Keys** in the left navigation bar and select **Create Key**.
4. Copy the key. It is shown **once** and cannot be retrieved later; if you lose it, delete the key and create another.

The page names the workspace and environment the new key will be created for. There is no scope picker: a key always takes the one you are viewing.

Creating keys is limited to account administrators. If your account has roles and permissions turned on, it is limited to users with the **User management** permission. Everyone else does not see **API Keys** in the navigation bar.

## Find, rename and delete keys

The **API Keys** page lists **your own keys for the workspace and environment you are viewing**. A colleague's keys are not listed for you, and switching workspace or environment switches the list. Rename a key, or delete it: deleting takes effect within a minute, and any integration using the key then stops working.

Some keys belong to no workspace or environment you can switch to, so they would be impossible to find and delete. They are listed in **every** workspace and environment view, with a label:

| Label | What it means |
| - | - |
| **Full account access** | Created before keys were tied to a workspace and an environment. It still works across your whole account. This is temporary: these keys will be moved onto a workspace and an environment, and the label goes away. |
| **Environment disabled** | The key's environment has been disabled. Within a minute of that, requests with the key are refused with `401` until the environment is enabled again. |
| **Workspace deleted** | The key's workspace was deleted. Within a minute of that, requests with the key are refused with `401`. Delete the key. |

## Check which workspace and environment a key is for

`GET /v1/auth/whoami` reports the workspace and environment behind a key:

```bash theme={null}
curl https://api.engini.io/v1/auth/whoami -H "x-api-key: $ENGINI_API_KEY"
```

```json theme={null}
{
  "fullName": "Jane Example",
  "email": "jane@example.com",
  "currentCompany": "Example Co.",
  "role": "Admin",
  "userType": "apiuser",
  "workspace": { "id": "00000000-0000-0000-0000-000000000000", "name": "Finance" },
  "environment": { "id": "00000000-0000-0000-0000-000000000000", "name": "Production", "type": "Production" }
}
```

`workspace` and `environment` are `null` for a key that has no scope (the **Full account access** label above) and for any caller that is not a key. `environment.type` is `Production`, `Staging` or `Development`.

## Errors a key can get

These come on top of the usual [error codes](/developers/get-started/pagination-errors-rate-limits#error-codes). Branch on `errorCode`.

| `errorCode` | Status | What it means | What to do |
| - | - | - | - |
| `API_KEY_NOT_ALLOWED` | 403 | The key called an endpoint outside the key API. A key can call the Developer API (`/v1`) and the Connector SDK; every other endpoint refuses it (a **Full account access** key is the one exception, see below). | Call a `/v1` endpoint. Operations only the app can do need a signed-in user. |
| `SCOPE_UNRESOLVED` | 403 | The key's workspace and environment could not be read, so the request did not run. This should not happen. | Retrying will not help. Send the `requestId` to support. |
| `MEMBERSHIP_CHECK_UNAVAILABLE` | 503 | Engini could not verify the key's account in time (a temporary problem or a timeout). Nothing ran. | Safe to retry: back off and send the same request again. |
| `SCOPE_READ_ONLY` | 403 | You tried to change something the key can see but does not own, for example a connection shared into the key's workspace and environment from another one. | Change it with a key (or a user) in the workspace and environment that owns it. |

A **Full account access** key (created before keys were tied to a workspace and an environment) may still reach some endpoints outside `/v1` until it is moved onto a workspace and an environment.

## Solutions are installed in the app, not with a key

Installing, updating and uninstalling a solution is done in the Engini app. An API key cannot do it: those three calls answer `403 API_KEY_NOT_ALLOWED`, whether or not the key has a scope.


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