# Owner-delegated personal-agent automation

`GET /api/developer/v1/agents` lists personal identities with **agents:read**.
`POST /api/developer/v1/agents` registers one identity with **agents:create**.
`GET /api/developer/v1/agents?agent_id=<stable ID>` retrieves an owned personal agent with **agents:read**.
`GET /api/developer/v1/agents?action=permissions` inspects the current credential without requiring additional scopes.
All operations use `Authorization: Bearer <hid_dev_credential>` and return `Cache-Control: no-store`.
POST requires JSON, up to 8 KiB. The credential's stored owner controls every operation;
caller-supplied account, company, permissions or classification overrides are rejected.

This reuses the canonical Identity workload/agent registry. Created identities appear
in the owner's personal inventory and existing Cortex inventory. Creation is not
Cortex profile linking or execution consent. New workload rows have **empty allowed
scopes**, no access tokens, no memory/knowledge grant, no company representation and
no wallet/trading configuration. Existing identities, keys and bindings are untouched.

## Explicit delegation and existing credentials

In **Developer Apps → Agent & automation access**, select either permission when
creating a credential. They are unchecked by default. For an existing active credential,
choose **Add personal-agent permissions**, select the required permissions and confirm
with the owner's authenticator. This adds permissions without removing existing ones,
changing the credential secret, or extending its original 30-day expiry.

The existing same-origin, authenticated `/api/identity/applications` owner endpoint
also accepts `{"action":"token-permissions-add","token_id":"<credential ID>",
"scopes":["agents:read","agents:create"],"code":"<current authenticator code>"}`.
The automation API cannot call that operation or grant itself more permissions.
Use the existing owner revoke action to withdraw a credential. Reissue explicitly
when it expires. Human browser tokens and OIDC client secrets cannot call this API.

## Inventory

```http
GET /api/developer/v1/agents?offset=0
Authorization: Bearer <developer credential>
```

```json
{"success":true,"data":{"schema":"HYBRID_AUTOMATION_AGENT_INVENTORY_V1","owner":"<32 hex owner ID>","items":[{"agent_id":"<32 hex stable agent ID>","name":"Personal assistant","status":"ACTIVE","representation":"personal","workspace":null}],"next_offset":null}}
```

Pages contain at most 50 records. Follow `next_offset` even if `items` is empty:
company-assigned and ineligible entries are filtered. Inventory contains no workload
keys, memory references, wallet data or execution claims. A stable agent identifier
is a reference, never an authorization capability. Inventory may allocate an alias
for an existing agent; it does not register another workload or change its permissions.

## Idempotent creation and proof

Generate an Ed25519 key in the agent's secure runtime and retain its private key there.
Send only its public JWK. Persist the following statement and a random 16-byte hex
operation ID **before** sending the request. `owner` comes from authenticated permission inspection or inventory. It is a signed
confirmation of the credential’s fixed owner, not an account selector; another owner is rejected. `name` is trimmed, 1–160 characters, with no control characters.

```json
{"owner":"<32 hex owner ID>","operation_id":"<32 hex operation ID>","name":"Approved personal agent name","public_key_jwk":{"kty":"OKP","crv":"Ed25519","x":"<43 base64url public key>"}}
```

Sign the UTF-8 bytes of `hybrid-id/automation-agent-creation/v1`, one zero byte,
then canonical JSON (recursively sorted keys, compact separators, Unicode unescaped).
The proof is an unpadded base64url Ed25519 signature. Never send a private JWK.

```js
import { sign } from 'node:crypto';
const canonical = value => Array.isArray(value)
  ? '[' + value.map(canonical).join(',') + ']'
  : value && typeof value === 'object'
    ? '{' + Object.keys(value).sort().map(k => JSON.stringify(k)+':'+canonical(value[k])).join(',') + '}'
    : JSON.stringify(value);
const proof = sign(null, Buffer.concat([
  Buffer.from('hybrid-id/automation-agent-creation/v1\0'),
  Buffer.from(canonical(statement)),
]), privateKey).toString('base64url');
// privateKey stays in your secure runtime; persist statement/proof for exact retries.
const response = await fetch('https://hybrid-id.com/api/developer/v1/agents', {
  method: 'POST', headers: {Authorization: `Bearer ${developerCredential}`, 'Content-Type':'application/json'},
  body: JSON.stringify({action:'agent-create', statement, proof}),
});
```

```json
{"success":true,"data":{"schema":"HYBRID_AUTOMATION_AGENT_CREATION_V1","owner":"<owner ID>","agent_id":"<stable agent ID>","name":"Approved personal agent name","status":"ACTIVE","representation":"personal","workspace":null,"classification":"REAL","replayed":false,"ownership_confirmed":true,"execution_enabled":false}}
```

The stable identity, empty-scope workload and receipt commit atomically. The operation
is scoped to owner + automation namespace + operation ID, independent of the credential
ID, so an explicitly permitted replacement credential can retry the same statement.
Exact retries return the same agent and `replayed:true`. Changed input under the same
operation ID fails with 400. Retries never rotate keys, restore revoked agents, or
create execution grants. REAL/SYNTHETIC classification is operator-controlled.

## Failures and withdrawal

Responses use the existing developer error envelope: `success:false` and `message`.
401 means an absent/expired/revoked credential; 403 means missing permission, an
inactive owner, changed authority or invalid key proof. 400 means invalid fields or
an operation ID reused with different input. 404 means the personal agent is absent or not owned by this account; these cases
are deliberately indistinguishable. 409 means the creation quota is reached.
429 is throttling; 503 is unavailable
or uncertain registry state. Follow bounded backoff on 429/503/network uncertainty
and retry the **exact** operation; do not allocate a replacement ID automatically.

Credential permission/expiry/revocation is checked before and after the registry call;
active personal ownership is also checked before commit. Withdrawn authority prevents
response disclosure and later retries. An already in-flight registration may commit
before credential withdrawal is observed; it still has no execution permissions.
Reconcile with a newly authorized inventory/read before attempting another operation.


## Credential inspection and individual retrieval

```http
GET /api/developer/v1/agents?action=permissions
Authorization: Bearer <developer credential>
```

```json
{"success":true,"data":{"schema":"HYBRID_AUTOMATION_CREDENTIAL_V1","id":"<64 hex credential ID>","label":"Cortex personal agent registration","owner":"<32 hex owner ID>","permissions":["agents:read","agents:create"],"expires_at":"<ISO 8601 UTC timestamp>"}}
```

The bearer is never returned. Only one query mode is accepted: offset, agent_id or
action=permissions. Owner, email, company and other selectors are rejected.

```http
GET /api/developer/v1/agents?agent_id=<32 hex stable ID>
Authorization: Bearer <developer credential>
```

```json
{"success":true,"data":{"schema":"HYBRID_AUTOMATION_AGENT_LOOKUP_V1","owner":"<32 hex owner ID>","agent_id":"<32 hex stable ID>","name":"Personal assistant","status":"ACTIVE","representation":"personal","workspace":null,"ownership_confirmed":true}}
```

Listing/lookup describe lifecycle and ownership, not permission to execute. Existing
agents may separately have other permissions; this API neither returns nor changes them.

## Limits, retention and auditing

Default creation quota: **100 active agents created through this automation namespace
per owner**, independent of how many credentials that owner issues. The operator may
configure `HYBRID_SSO_AUTOMATION_AGENT_LIMIT` (1–10000). Existing exact-owner unlimited
policy is respected; no blanket administrator bypass is added. Quota checks and new
registrations share an owner/namespace lock and transaction. Exact retries remain
valid at the limit. Revoked identities retain their receipts and are not resurrected.
The existing shared developer request rate is **120 requests per owner per 60 seconds**;
its explicitly configured unlimited owner exemption remains in place. An operation
already being committed can return 503; retry with bounded backoff and the same ID.

Durable receipts retain owner, namespace, operation ID, statement digest, stable agent
ID and operator classification. Provider audit records contain credential ID, owner,
action and target agent, never bearer tokens or private keys. Receipts do not expire
with the automation credential. Credential validity is 30 days; no refresh token is
issued. Rotate by explicitly creating another narrowly scoped credential and revoking
the old one after migration. This API cannot issue credentials or expand permissions.


## Delegated private Cortex linking

The [private automation owner-mapping contract](cortex-agent-owner.md) provides the
current account mapping without a browser session. It grants no Cortex write permission;
Cortex must separately enforce an explicit linking delegation and its own atomic setup/link
transaction. Existing signed-in linking remains supported. Never create replacements.
