# Agent Auth API

These endpoints register agents, identify the current bearer token, and manage
API key metadata.

## POST /api/v1/agents/register

Register one agent and issue a one-time API key.

Authentication: none.

Request body fields:

| Field              | Type           | Required | Meaning                                                                                  |
| ------------------ | -------------- | -------- | ---------------------------------------------------------------------------------------- |
| `principal_id`     | UUID or null   | No       | Existing principal that owns or represents the agent.                                    |
| `agent_type`       | string enum    | Yes      | One of `human`, `scraper`, `api_agent`, `supplier_agent`, `customer_agent`, or `sensor`. |
| `display_name`     | string         | Yes      | Public label for the agent.                                                              |
| `description`      | string or null | No       | Short public description of what the agent does.                                         |
| `status`           | string enum    | No       | Defaults to `active`; allowed values are `active`, `paused`, `disabled`.                 |
| `score_trust`      | decimal        | No       | Initial trust score from `0` to `1`; defaults to `0.5`.                                  |
| `score_reputation` | decimal        | No       | Initial reputation score from `0` to `1`; defaults to `0.5`.                             |
| `capabilities`     | object         | No       | Structured capability hints, such as supported entry types or source domains.            |
| `metadata`         | object         | No       | Extra public or operational metadata.                                                    |

Response fields:

| Field     | Meaning                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------- |
| `agent`   | Created agent record.                                                                           |
| `api_key` | One-time raw bearer token. Store it immediately; it is not returned later.                      |
| `key`     | API key metadata, including `id`, `agent_id`, `key_prefix`, `status`, `scopes`, and timestamps. |

Example:

```http
POST /api/v1/agents/register
Content-Type: application/json
```

```json
{
  "display_name": "Bologna service scraper",
  "agent_type": "scraper",
  "capabilities": {
    "entry_types": ["entity", "listing"],
    "source_types": ["web_page"]
  },
  "metadata": {
    "operator": "example-ingestion-service"
  }
}
```

## GET /api/v1/agents/me

Return the active agent associated with the bearer token.

Authentication: required.

```http
GET /api/v1/agents/me
Authorization: Bearer stap_live_...
```

Returns `401` when the token is invalid, revoked, expired, or belongs to a
disabled agent.

## GET /api/v1/agents/me/api-keys

List API key metadata for the authenticated agent.

Authentication: required.

```http
GET /api/v1/agents/me/api-keys
Authorization: Bearer stap_live_...
```

The raw `api_key` is never included in list responses. Use `key_prefix`,
`status`, timestamps, and `scopes` for inventory and rotation.

## POST /api/v1/agents/me/api-keys

Create an additional API key for the authenticated agent.

Authentication: required.

Request body fields:

| Field                   | Type             | Required | Meaning                                     |
| ----------------------- | ---------------- | -------- | ------------------------------------------- |
| `scopes`                | string array     | No       | Defaults to `["space_time_entries:write"]`. |
| `expires_at_tstamp_utc` | datetime or null | No       | Optional UTC expiry timestamp.              |

Example:

```http
POST /api/v1/agents/me/api-keys
Authorization: Bearer stap_live_...
Content-Type: application/json
```

```json
{
  "scopes": ["space_time_entries:write"],
  "expires_at_tstamp_utc": "2026-12-31T23:59:59Z"
}
```

The response includes a one-time `api_key` plus key metadata.

## DELETE /api/v1/agents/me/api-keys/{key_id}

Revoke one API key belonging to the authenticated agent.

Authentication: required.

```http
DELETE /api/v1/agents/me/api-keys/11111111-1111-1111-1111-111111111111
Authorization: Bearer stap_live_...
```

Returns `204` when revoked. Returns `404` when the key does not exist or does
not belong to the authenticated agent.

## Bearer Token Usage

Send the token exactly as:

```http
Authorization: Bearer stap_live_...
```

Use the bearer token for authenticated write endpoints such as
`POST /api/v1/space-time-entries`. Do not send raw keys in query strings or request
bodies.