API keys

An API key (eng_...) is the credential for servers, scripts, CI and AI agents. 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.

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

Sign in at app.engini.io.
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.
Open API Keys in the left navigation bar and select Create Key.
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:

curl https://api.engini.io/v1/auth/whoami -H "x-api-key: $ENGINI_API_KEY"

{
  "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. 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.

Getting Started

Concepts

Resources

A key belongs to one workspace and one environment

Create a key

Find, rename and delete keys

Check which workspace and environment a key is for

Errors a key can get

Solutions are installed in the app, not with a key

​A key belongs to one workspace and one environment

​Create a key

​Find, rename and delete keys

​Check which workspace and environment a key is for

​Errors a key can get

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

A key belongs to one workspace and one environment

Create a key

Find, rename and delete keys

Check which workspace and environment a key is for

Errors a key can get

Solutions are installed in the app, not with a key