Auth and Permissions

Authentication and RBAC guidance for customer-facing Selwise APIs.

Audience: Engineers configuring secure API access for teams and integrations.

Critical: Private endpoints require JWT Bearer auth; public runtime endpoints use siteKey + public guard protections instead of JWT.

API Endpoints Security and Rate Limits Errors and Retries

Who This Page Is For

Use this page when assigning API access roles and clarifying permission boundaries across modules, analytics, integrations, AI, and scripts.

Quick Start (2-5 Minutes)

Authenticate user

Use login flow to obtain token for private API calls.

POST /api/v1/auth/login

Attach Bearer token

Send Authorization header on private routes.

Authorization: Bearer <token>

Map role to required permissions

Ensure role grants module-level actions (view/create/update/delete/publish/etc.).

Example: campaign:publish required for publish endpoint.

Validate site-scoped access

Private site-scoped endpoints also require organization/site ownership checks.

Use least-privilege role assignments.

Separate public runtime calls

Do not send Bearer tokens to public siteKey endpoints.

Public endpoints rely on site/origin/subscription guards.

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`Authorization`	Required	`Bearer token`	Private endpoints	JWT token issued by auth endpoints.
`Permission`	Conditional	`RBAC capability string`	Private endpoints	Specific permission required per route action.
`siteId organization access`	Conditional	`scope check`	Site-scoped private routes	User must belong to organization owning site.
`siteKey`	Conditional	`string`	Public runtime endpoints	Used instead of JWT on public endpoints.

Representative permission families

widget:view|create|update|delete
campaign:view|create|update|delete|publish
reco:view|create|update|delete
search:view|update|manage_synonyms|manage_redirects|manage_boosts|view_zero_results|resolve_zero_results
segment:view|create|update|delete|view_members
experiment:view|create|update|delete|view_results
analytics:view|export|view_revenue
ai:generate|view_usage|configure
script:view|create|update|delete|activate
site:view|create|update|delete|verify_domain
email:sender_view|sender_manage|sender_verify

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need private module access	JWT + module permission	RBAC-enforced least privilege.
Need analytics dashboards	analytics:view permission	Required for analytics route family.
Need SMTP sender onboarding	*email:sender_ permissions**	Sender create/test/verify/default flows are permission-gated.
Need email open/click/unsubscribe tracking	Signed tracking token (no JWT)	Public email tracking routes are token-authorized instead of RBAC-authorized.
Need publish/go-live actions	Action-specific permissions (for example campaign:publish)	Protects high-impact transitions.
Need public storefront runtime	siteKey endpoints without JWT	Public guard model is separate from user auth model.
Need role troubleshooting	Check permission enum mapping and route decorators	Directly explains 403 causes.

Common Errors and Fixes

401 Unauthorized

Cause: Missing/expired/invalid JWT token.

Fix: Refresh token and include valid Bearer header.

403 Forbidden on private route

Cause: Token valid but permission missing for requested action.

Fix: Grant required permission for role or use authorized role account.

403 on site-scoped analytics route

Cause: User does not have access to requested site organization.

Fix: Use site under same organization or authorized super-admin account.

403 on sender verify endpoint

Cause: Role has sender view/manage but lacks verify capability.

Fix: Grant email:sender_verify or perform verification with admin/super_admin role.

Public endpoint blocked despite no JWT need

Cause: site/origin/subscription guard failure.

Fix: Validate siteKey, domain origin, and subscription status.

Public email tracking endpoint returns invalid token

Cause: Signed tracking token expired or malformed.

Fix: Generate links from campaign renderer and ensure EMAIL_TRACKING_SECRET consistency across instances.

Production Checklist

Roles are designed with least-privilege module access.Required
Publish/delete/update actions are restricted to trusted roles.Required
SMTP sender permissions are separated by view/manage/verify responsibilities.Required
Token lifecycle and refresh handling is implemented in clients.Required
Public runtime integrations do not leak private JWT tokens.Required
Permission audits are performed on role changes.Required