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.

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

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.

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

{
  "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:

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.