> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehasp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Registering Agents

> Create a persistent agent identity in your org via dashboard or API.

An agent registration creates a persistent identity in your org. No credentials are issued at registration — you issue them separately after the agent is registered.

## Dashboard

**Developers → Agents → Register an agent**

| Field                     | Required | Description                                                                                                                                                                                                  |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Display name              | Yes      | Human-readable name, unique within your org. 2–64 characters.                                                                                                                                                |
| Capabilities              | No       | Short descriptive tags (e.g. `chart-review`, `scheduling-handoff`). Up to 12 tags, 32 chars each.                                                                                                            |
| Default expiry            | Yes      | Default expiry for credentials issued to this agent. 1 hour to 30 days.                                                                                                                                      |
| Default revocation policy | Yes      | `drain` or `kill`. Used when issuing a credential without an explicit policy.                                                                                                                                |
| Allowed scope types       | No       | Scope types that credentials issued to this agent may carry. Leave blank to allow all scope types. Agents blocked from a scope type cannot receive credentials with that scope regardless of who is issuing. |

After registration, you land on the agent detail page which links directly to issuing the first credential.

## API

```
POST https://api.usehasp.com/v1/agents
Authorization: Bearer hasp_api_live_...
Content-Type: application/json
```

### Body

```json theme={null}
{
  "name": "IntakeRouter",
  "capabilities": ["chart-review", "scheduling-handoff"],
  "default_expiry_hours": 8,
  "default_revocation_policy": "drain",
  "allowed_scope_types": [
    "hasp.data.read",
    "hasp.data.write",
    "external.tool.invoke"
  ]
}
```

### Fields

| Field                       | Type              | Required | Description                                           |
| --------------------------- | ----------------- | -------- | ----------------------------------------------------- |
| `name`                      | string            | Yes      | Unique display name within the org. 2–64 chars.       |
| `capabilities`              | string\[]         | No       | Descriptive tags. Max 12, 32 chars each.              |
| `default_expiry_hours`      | integer           | Yes      | 1–720.                                                |
| `default_revocation_policy` | `drain` \| `kill` | Yes      | Default policy for newly issued credentials.          |
| `allowed_scope_types`       | string\[] \| null | No       | Scope type allowlist. `null` permits all scope types. |
| `description`               | string            | No       | Optional long-form description.                       |

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "agent": {
      "id": "01JQAGENT0000000000000000",
      "name": "IntakeRouter",
      "capabilities": ["chart-review", "scheduling-handoff"],
      "default_expiry_hours": 8,
      "default_revocation_policy": "drain",
      "allowed_scope_types": ["hasp.data.read", "hasp.data.write", "external.tool.invoke"],
      "status": "active",
      "created_at": "2026-05-11T12:00:00+00:00"
    }
  }
}
```

### Errors

| Code                 | HTTP | Meaning                                                    |
| -------------------- | ---- | ---------------------------------------------------------- |
| `AGENT_NAME_TAKEN`   | 422  | An active agent with this name already exists in your org. |
| `INVALID_SCOPE_TYPE` | 422  | `allowed_scope_types` contains an unrecognized scope type. |

***

## Listing agents

```
GET https://api.usehasp.com/v1/agents
Authorization: Bearer hasp_api_live_...
```

### Query parameters

| Parameter  | Description                               |
| ---------- | ----------------------------------------- |
| `status`   | `active` (default), `archived`, or `all`. |
| `search`   | Filter by name or ID prefix.              |
| `page`     | Page number.                              |
| `per_page` | Results per page (default 25, max 100).   |

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "01JQAGENT0000000000000000",
      "name": "IntakeRouter",
      "capabilities": ["chart-review"],
      "status": "active",
      "active_credential_count": 2,
      "created_at": "2026-05-11T12:00:00+00:00"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "last_page": 1
  }
}
```

***

## Retrieving a single agent

```
GET https://api.usehasp.com/v1/agents/{agent_id}
Authorization: Bearer hasp_api_live_...
```

***

## Updating agent settings

```
PATCH https://api.usehasp.com/v1/agents/{agent_id}
Authorization: Bearer hasp_api_live_...
Content-Type: application/json
```

Updatable fields: `name`, `description`, `capabilities`, `default_expiry_hours`, `default_revocation_policy`, `allowed_scope_types`.

Emits `agent.metadata_updated` on any actual change.

***

## Archiving an agent

Archiving immediately revokes all active credentials (with `kill` policy) and prevents new credentials from being issued.

```
POST https://api.usehasp.com/v1/agents/{agent_id}/archive
Authorization: Bearer hasp_api_live_...
```

Returns the IDs of all revoked credentials.

Archived agents can be reactivated:

```
POST https://api.usehasp.com/v1/agents/{agent_id}/reactivate
Authorization: Bearer hasp_api_live_...
```

Reactivation does not restore previously revoked credentials.