# Authentication

> Create an API key and choose its Workspace permissions.

Send your key in the `Authorization` header, after the word `AugentaKey`:

```http
Authorization: AugentaKey <your key>
```

## Create a key

In the [console](https://augenta.pages.dev/dashboard/keys), open **API Keys** → **New API Key**.
Give it a label and optionally select the Workspaces it can access. Augenta has one API key
type: every key can make stateless requests, and Workspace assignments add read/write permissions
for managed memory. No Connector setup is required.

| Assigned Workspaces | Access                                                                                |
| ------------------- | ------------------------------------------------------------------------------------- |
| None                | One-shot Consolidate only: omit workspace and read the returned Claims and Engrams.   |
| One                 | Read and write that Workspace. Requests that allow omission infer this destination.   |
| Multiple            | Read and write any assigned Workspace. Name one destination on each stateful request. |

Every Workspace assignment grants both reads and writes. A request operates on one Workspace;
it does not broadcast to all assignments. Keys with assignments can also make stateless calls.
The issuer must administer every selected active Workspace. You can create a key with no Workspace
assignments in your personal account. In a shared organization, its owner or an admin issues those keys.

Save the one-time secret in your secret manager before leaving the page. A key belongs to the
account where it was created and keeps working if its creator leaves; revoking it, or retiring the
account, stops it.

Create Workspaces and keys in the console. API keys can't administer keys or Workspaces: the
administration API accepts only a signed-in person's credentials (`Authorization: Bearer <token>`),
which is what the console uses. For reference, the same operation creates a key with no
Workspace permissions from:

```json
{
  "label": "Hello world",
  "workspaceIds": []
}
```

Or assign Workspace access with the same `POST /v1/orgs/{id}/keys` operation:

```json
{
  "label": "My service",
  "workspaceIds": [
    "ws-product",
    "ws-research"
  ]
}
```

Omitting `workspaceIds` also creates a key with no assignments. See
[Create an API key](https://augenta.pages.dev/docs/api-reference/create-api-key.md).

## Stateless requests

Use any API key with [Hello world](https://augenta.pages.dev/docs/quickstart.md), including one with assigned Workspaces. Omit workspace
to make a one-shot request. Augenta returns claims and engrams without storing anything. Assign a Workspace for persistence and later retrieval.

Keys without assignments cannot access durable Workspace memory.

## Choose a Workspace

For stateful calls, select a Workspace assigned to the key:

| Operation                            | Workspace selector                                                  |
| ------------------------------------ | ------------------------------------------------------------------- |
| Consolidate                          | Body `workspace` is required.                                       |
| Experiences (`POST /v1/experiences`) | Body `workspace`; inferred when exactly one Workspace is assigned.  |
| Recall                               | Body `workspace`; inferred when exactly one Workspace is assigned.  |
| Engram and Event reads               | Query `workspace`; inferred when exactly one Workspace is assigned. |
| Document upload                      | Workspace in the URL.                                               |
| Experience status                    | Workspace determined from the experience id.                        |

An unassigned Workspace returns `403`. A missing selector on a request that cannot infer one
returns `400 invalid_request`. Archiving one assigned Workspace stops access to that Workspace
while other assignments remain usable. Deleting it removes its assignment; a key left with no
assignments becomes stateless-only. Revocation stops future access and retains work already accepted.

## Keys created for a Connector

Keys created earlier for a Connector, such as the coding-agent plugin's, keep working. Each one
reads and writes only its Connector's Workspace, and it stops when that Connector is disabled or
its Workspace is archived. New integrations don't need a Connector.

> Warning:
>
> Treat a key like a password: keep it out of source control, logs, and agent conversations.

## Revoke a key

Open **API Keys** in the console and revoke it. Only that key stops working; other keys remain
available. Organization owners/admins can list every key, including keys whose creator has left, and revoke any of them. Other members can list and revoke their own keys.
