Access Denied

forbidden-access · 403

The API knows who is calling, but the caller's seat or permissions don't allow this call.

requiredPermission names what was missing. When the seat is too low, it usually lists the seats that would pass and resourceType is Workspace. When the account lacks a permission, it lists the missing permissions, such as cloud:projects:delete, and resourceType is Cloud.

Besides the members every error carries, this type adds requiredPermission, resourceType and resourceId.

Common causes

  • The caller's seat in the workspace is viewer, and the call writes. Every write needs developer or above.
  • The call is about money, and only the organization roles it names may make it, such as owner and admin.
  • The account doesn't hold a permission the route needs, such as an admin route's.
  • Applying a changeset that deletes a service or a database copy needs cloud:projects:delete. resourceType is then Changeset.

How to fix the call

  • Read requiredPermission and tell the user exactly what is missing, quoting detail.
  • Don't retry, and don't attempt the same change through a different endpoint: every route makes the same check.
  • A seat change is for an admin of the workspace to make, not something to work around.

Example response

json
{
  "type": "forbidden-access",
  "title": "Access Denied",
  "detail": "Your seat in this workspace is 'viewer'; this action needs admin or developer",
  "requiredPermission": "admin, developer",
  "resourceType": "Workspace",
  "resourceId": "current",
  "requestId": "req-1785231000000-4f7b2c9ae",
  "timestamp": "2026-07-28T09:30:00.000Z",
  "path": "/v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401",
  "method": "DELETE",
  "instance": "DELETE /v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401",
  "status": 403,
  "docs": "https://ghaym.me/docs/errors/forbidden-access"
}