Portal Permissions
Control what your customers can do in the Developer Portal
Portal sessions use granular permissions to control what your customers can do. Permissions are resource-scoped with read, write, and delete levels.
Permission Scopes
| Permission | Description |
|---|---|
endpoints:read | View endpoints and their configuration |
endpoints:write | Create and update endpoints |
endpoints:delete | Delete endpoints |
subscriptions:read | View event type subscriptions |
subscriptions:write | Subscribe and unsubscribe from event types |
event_types:read | View available event types |
deliveries:read | View delivery history and attempt details |
Roles (Convenience Presets)
Instead of specifying individual permissions, you assign a role when creating a portal session. Each role maps to a predefined set of permissions:
| Permission | admin | editor | viewer |
|---|---|---|---|
endpoints:read | Yes | Yes | Yes |
endpoints:write | Yes | Yes | - |
endpoints:delete | Yes | - | - |
subscriptions:read | Yes | Yes | Yes |
subscriptions:write | Yes | Yes | - |
event_types:read | Yes | Yes | Yes |
deliveries:read | Yes | Yes | Yes |
- admin — full access including endpoint deletion
- editor — create and update, but cannot delete (default)
- viewer — read-only access across all resources
Assigning Permissions
Pass the role parameter when creating a portal session:
curl -X POST https://api.nahook.com/management/v1/workspaces/{workspaceId}/applications/{appId}/portal \
-H "Authorization: Bearer nhm_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"role": "editor",
"expiresInMinutes": 60
}'If role is omitted, it defaults to editor.
Use viewer for customers who should only inspect their webhook deliveries without making changes. Use editor for most customers — they can set up and modify endpoints without risk of accidental deletion. Reserve admin for customers who need full self-service control.
Permission Enforcement
Permissions are checked on every API call. When a portal user attempts an action their role doesn't permit, the API returns 403 Forbidden with the specific permission that was missing:
{
"error": {
"code": "forbidden",
"message": "Insufficient permissions: requires endpoints:delete"
}
}The role is set at session creation and cannot be changed during the session. To change a customer's access level, create a new portal session with a different role.
Delivery History
All roles (including viewer) can view delivery history for their endpoints:
- Delivery list —
GET /portal/endpoints/:id/deliveries— status, attempt count, and timestamps - Delivery detail —
GET /portal/endpoints/:id/deliveries/:deliveryId— individual attempt results including response status codes, response times, and error messages
This gives your customers visibility into webhook reliability without needing to contact your support team.