# Create an API key

## POST `/v1/orgs/{id}/keys`

Use workspaceIds to assign zero or more active Workspaces in the organization. The issuer must administer every assignment. With no assignments, the key is stateless-only and requires an organization owner/admin to issue. No Connector is required. Legacy Connector keys require the Connector owner or an organization owner/admin. The secret appears once. Direct keys are organization-owned and survive removal of their creator.

## Authentication

Use a person's Bearer access token or console session. See [Authentication](https://augenta.pages.dev/docs/authentication.md).

## Request example

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

## Parameters

<a id="request-parameters-id"></a>

### `request.parameters.id`

`string` · required

path parameter.

Min length: `1`.

## Body fields

Create a key with zero or more assigned Workspaces. Omit workspaceIds or send \[] for stateless-only access. Each assigned Workspace grants reads and writes. Legacy Connector issuance is also supported. Labels are trimmed and capped at 120 characters.

**Option 1**

<a id="request-body-option-1-label"></a>

### `request.body.option-1.label`

`string` · required

Min length: `1`.

<a id="request-body-option-1-workspaceids"></a>

### `request.body.option-1.workspaceIds`

`array<string>` · optional

Default: `[]`.

**Option 2**

<a id="request-body-option-2-label"></a>

### `request.body.option-2.label`

`string` · required

Min length: `1`.

<a id="request-body-option-2-connectorid"></a>

### `request.body.option-2.connectorId`

`string` · required

Min length: `1`.

## Response 201

Save the secret now; it cannot be retrieved later.

Content-Type: `application/json`

```json
{
  "secret": "<copy this one-time secret>",
  "object": "api_key",
  "id": "sk-aug-example-public-id",
  "orgId": "aug-example",
  "workspaceIds": [],
  "label": "Hello world",
  "createdByUserId": "user-example",
  "createdAt": "2026-10-22T12:00:00Z"
}
```

<a id="response-201-object"></a>

### `response.201.object`

`string` · always present

The resource type. Always api_key.

Allowed values: `"api_key"`.

<a id="response-201-id"></a>

### `response.201.id`

`string` · always present

Public credential identity used in administration routes. It is not the authentication secret.

Min length: `1`.

<a id="response-201-orgid"></a>

### `response.201.orgId`

`string` · always present

Owning Organization's Augenta ID.

Min length: `1`.

<a id="response-201-label"></a>

### `response.201.label`

`string` · always present

Human-readable credential name.

<a id="response-201-createdbyuserid"></a>

### `response.201.createdByUserId`

`string` · always present

Person who issued the credential.

<a id="response-201-createdat"></a>

### `response.201.createdAt`

`string` · always present

Recorded credential creation time.

<a id="response-201-scope"></a>

### `response.201.scope`

`string` · conditional

Scope metadata, when present.

<a id="response-201-workspaceids"></a>

### `response.201.workspaceIds`

`array<string>` · conditional

Assigned Workspaces. An empty array permits one-shot Consolidate only.

<a id="response-201-workspaceid"></a>

### `response.201.workspaceId`

`string` · conditional

Legacy single-Workspace assignment, when applicable.

<a id="response-201-connectorid"></a>

### `response.201.connectorId`

`string` · conditional

Legacy Connector-backed credential reference, when applicable.

<a id="response-201-lastactiveat"></a>

### `response.201.lastActiveAt`

`string` · conditional

Last recorded authentication activity, when available.

<a id="response-201-revokedat"></a>

### `response.201.revokedAt`

`string` · conditional

Recorded revocation time, when revoked.

<a id="response-201-secret"></a>

### `response.201.secret`

`string` · always present

## Response 400

invalid_request: invalid fields or destination.

Content-Type: `application/json`

<a id="response-400-error"></a>

### `response.400.error`

`object` · always present

<a id="response-400-error-code"></a>

### `response.400.error.code`

`string` · always present

Stable. The Errors page lists every code.

<a id="response-400-error-message"></a>

### `response.400.error.message`

`string` · always present

Human-readable. May change; don't parse it.

<a id="response-400-error-retryable"></a>

### `response.400.error.retryable`

`boolean` · always present

<a id="response-400-error-retryafterseconds"></a>

### `response.400.error.retryAfterSeconds`

`integer` · conditional

Capacity retry interval, also present as Retry-After before stream headers commit. SSE error events retain this field after HTTP 200 is committed.

Minimum: `1`.

<a id="response-400-error-billingurl"></a>

### `response.400.error.billingUrl`

`string` · conditional

Top-up action when error.code is insufficient_balance (HTTP 402).

<a id="response-400-requestid"></a>

### `response.400.requestId`

`string` · always present

The request's id, as in the `X-Request-Id` response header.

## Response 401

unauthenticated: sign in first.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 403

forbidden: this action requires a person with the necessary role; API keys cannot administer resources.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 404

not_found: the key is unavailable.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 409

conflict: the operation could not be completed.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 429

rate_limited: retry after Retry-After.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 500

internal_error: quote requestId when reporting a failure.

Content-Type: `application/json`

Response fields use the same schema as Response 400.
