# API keys

> Create credentials, inspect metadata and revoke future access.

An API key authorizes developer memory requests. Every key supports one-shot Consolidate; assigned
Workspaces additionally permit stored-memory reads and writes. Key administration requires a
person's credentials. The issuing person must administer each assigned Workspace.

See [the API key object](https://augenta.pages.dev/docs/api-reference/api-key-object.md) for its available operations, all attributes and an example object.

## Endpoints

| Endpoint                                                                                       | Purpose                                              |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [`POST /v1/orgs/{id}/keys`](https://augenta.pages.dev/docs/api-reference/create-api-key.md)           | Create a credential and receive its one-time secret. |
| [`GET /v1/orgs/{id}/keys`](https://augenta.pages.dev/docs/api-reference/list-api-keys.md)             | List visible key metadata.                           |
| [`GET /v1/orgs/{id}/keys/{keyId}`](https://augenta.pages.dev/docs/api-reference/get-api-key.md)       | Retrieve metadata for one key.                       |
| [`DELETE /v1/orgs/{id}/keys/{keyId}`](https://augenta.pages.dev/docs/api-reference/revoke-api-key.md) | Revoke that credential.                              |

## Fields

| Field                                 | Meaning                                                                               |
| ------------------------------------- | ------------------------------------------------------------------------------------- |
| `object`                              | Always `api_key`.                                                                     |
| `id`, `orgId`                         | Public key identity and its owning Organization. Neither is an authentication secret. |
| `label`                               | Human-readable name.                                                                  |
| `workspaceIds`                        | Assigned Workspaces. An empty array means one-shot-only access.                       |
| `scope`, `workspaceId`, `connectorId` | Scope metadata; some fields apply to older Connector-backed credentials.              |
| `createdByUserId`, `createdAt`        | Recorded issuer and creation time.                                                    |
| `lastActiveAt`, `revokedAt`           | Activity and revocation time, when recorded.                                          |
| `secret`                              | Returned only when creating a key. Never present in lists or retrieval.               |

Owners and administrators can manage organization-owned credentials even if their creator has
left. Other members can inspect and revoke only credentials they created. Lists have the shared
`data` and `nextPageUrl` envelope; the default limit is 50 and the maximum is 200.

## Create a one-shot-only key

```bash
curl --fail-with-body -sS "https://api.augenta.ai/v1/orgs/$AUGENTA_ORG_ID/keys" \
  -H "Authorization: Bearer $AUGENTA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"label":"Memory client","workspaceIds":[]}'
```

The `201` body is an `api_key` resource with a `secret` field alongside its metadata. Save that
secret directly in your application's secret configuration. Send it as `Authorization: AugentaKey`
for developer requests; use the public `id` in administration routes. The secret and its hash
cannot be read back through a resource endpoint.

Revocation returns `{object: "api_key", id, revoked: true}`. Future authentication with the secret
fails. Work already durably accepted remains in its Workspace, and an associated Connector is not
disabled by revoking one credential.
