# Projects And Settings

A Hooksbase project is your isolation boundary for billing, auth, quotas, webhooks, deliveries, and team access. Most of the product makes more sense once you treat the project as the root object that everything else belongs to.

**Available through**

Create and delete projects in the dashboard. Use public project routes for metadata, API keys, and audit reads.

| Surface | Status | Notes |
| --- | --- | --- |
| [Dashboard](/docs/dashboard.md) | Preferred | Project creation, deletion, logo management, team access, and billing context live in the UI. |
| [Public API](/docs/api-reference.md#project-and-api-keys) | Available | Use project routes for metadata, key lifecycle, usage context, and audit logs when the key role allows it. |
| [TypeScript SDK](/docs/sdks.md) | Available | The SDK can read and update the current project. |
| [CLI](/docs/cli.md) | Available | The CLI validates profiles and reads current project detail for admin-key profiles. |

## Project boundary

Each project owns:

- webhook definitions and their secrets
- delivery history, replay jobs, and DLQ entries
- team membership and invitations
- billing state and plan tier
- project-scoped API keys
- project metadata and logo assets

If you need different billing, different teams, or separate delivery history, use different projects instead of overloading one project with unrelated workloads.

## Auth model

- **Dashboard** `session auth`: Create, inspect, rename, and delete projects from the [Hooksbase dashboard](https://app.hooksbase.com). Project creation and deletion are dashboard-only flows.
- **Public API** `admin project key`: Use `/v1/project` and `/v1/project/api-keys` for project metadata and project-key management. Write keys cannot manage this surface.
- **CLI / SDK**: The SDK exposes project reads and updates. The CLI can validate the current project profile and read project detail when the key role allows it.

## Create and manage projects

New projects are created through the dashboard. Hooksbase provisions the project, creates the linked auth organization, and seeds guided onboarding state inside project metadata.

Once the project exists, you can:

- update project name and metadata
- control overage allowance when the current plan supports it
- inspect project-scoped quota detail
- view usage and audit information

Free-tier projects cannot enable overage. Project slug changes are intentionally not part of the public customer surface after creation.

## Settings, API keys, and logo

Treat project settings and project API keys as separate control planes:

- **Dashboard settings** cover the project name, overage allowance, quota visibility, branding, and the logo. These are dashboard-only flows.
- **Public API project routes** cover project metadata reads and patches (`GET /v1/project`, `PATCH /v1/project`).
- **Project API key routes** govern which admin and write credentials exist for the project (`GET/POST /v1/project/api-keys` and the revoke and rotate actions).

Logo management is a dashboard-only product flow. Supported upload types are PNG, JPEG, WebP, and SVG, capped at 256 KB. Upload, replace, or remove the logo from the project settings view.

Project admins can create, revoke, and rotate project API keys from either the dashboard or the Public API. Raw secrets are returned only on create and rotate responses; write keys still cannot manage `/v1/project` or any project-key management route.

**Create a write API key**

```bash
curl https://api.hooksbase.com/v1/project/api-keys \
  -H "Authorization: Bearer swk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-bot",
    "role": "write"
  }'
```

**Create-key response**

```json
{
  "apiKey": "swk_...",
  "key": {
    "id": "key_123",
    "name": "deploy-bot",
    "role": "write",
    "revokedAt": null
  }
}
```

Audit logs are read-only and available to admin keys when the project tier allows them:

**List audit logs**

```bash
curl -G https://api.hooksbase.com/v1/project/audit-logs \
  -H "Authorization: Bearer swk_..." \
  -d limit=20
```

Related routes:

- `GET/PATCH /v1/project`
- `GET/POST /v1/project/api-keys`
- `POST /v1/project/api-keys/{keyId}/revoke`
- `POST /v1/project/api-keys/{keyId}/rotate`
- `GET /v1/project/audit-logs`
- `GET /v1/project/audit-logs/{id}`

## Deletion behavior

Project deletion is destructive:

- Hooksbase deletes the project and its linked auth organization
- the stored logo object is cleaned up best-effort before the project row is removed
- the response is `204 No Content`
- deleting a project removes the customer-facing container for webhooks, deliveries, team membership, billing state, and onboarding state together

Export anything you still need before deletion. This action is not a soft delete and it is not a retention-only archive.

## Common mistakes

- Treating project metadata as an application database instead of small control-plane state.
- Deleting a project without exporting or preserving the delivery history you still need.
- Assuming write keys can manage project settings or project API keys.
- Treating logo upload as a Public API feature. It is dashboard-only.