Provider User Management - kurnl Developer Docs

These endpoints live on the internal API (/api/v1) and authenticate with a dashboard JWT (Authorization: Bearer ...), not an API key. Only the provider admin account (role service_provider with sub-role sp_admin or none) may manage staff. All operations are scoped to your own provider — other providers’ users are never visible.

Endpoints

Method	Path	Description
`GET`	`/api/v1/provider/users`	List your provider’s staff users
`POST`	`/api/v1/provider/users/invite`	Invite a staff member
`PATCH`	`/api/v1/provider/users/{user_id}/sp-role`	Change a staff member’s sub-role
`POST`	`/api/v1/provider/users/{user_id}/resend-invite`	Resend a pending invite email
`DELETE`	`/api/v1/provider/users/{user_id}`	Remove a staff user (204)

Sub-roles

Valid sp_role values: sp_admin, support, sales, bookkeeping. Invited users are always created with role service_provider under your service_provider_id — there is no admin or cross-provider escalation path.

POST /api/v1/provider/users/invite

{
  "email": "staff@yourisp.com",
  "sp_role": "support",
  "redirect_base_url": "https://dashboard.example.com (optional)"
}

Response — 201 Created

{
  "id": "uuid",
  "email": "staff@yourisp.com",
  "role": "service_provider",
  "sp_role": "support",
  "service_provider_id": "uuid"
}

The invitee receives an email with a password-set link.

Error codes

Status	Meaning
`400`	Invalid `sp_role`, or your account is not linked to a provider — also `You cannot remove your own account.`, `User has already accepted their invite` (resend), and auth-service errors passed through on update/delete
`403`	Caller is not the provider admin (staff sub-roles cannot manage users)
`404`	Target user not found in your provider
`409`	Email already registered (invite)
`500`	Auth service returned no user on create
`502`	`Auth service error` — the common upstream failure; safe to retry

GET /provider/users returns a bare list of user summaries; POST /{user_id}/resend-invite returns {"ok": true}. The password-set link (…/reset-password?token=…) is emailed asynchronously, fire-and-forget.