Management API (server-to-server)

Manage users, roles, branding, webhooks and audit logs from your backend with a scoped API key — no signed-in user required.

The Management API lets your backend read and change tenant data without a signed-in user — provisioning users, assigning roles, updating branding, managing webhook subscriptions, and reading the audit log. It is authenticated with a tenant-scoped API key and gated by scopes.

This is the same model the major identity providers use (Auth0 Management API, Okta API tokens, Microsoft Graph app-only): a separate machine-to-machine surface, distinct from the end-user OIDC sign-in flow.

Self-service vs. management. An end user changing their own profile, avatar, password, MFA or consent does that on Signward's hosted pages — your app redirects them there. The Management API acts on other users, as an admin/automation would. Use the right surface for the job.

1. Create an API key

In the Portal, go to API keys, create a key, and grant it only the scopes it needs (least privilege). The full key is shown once — store it as a secret in your backend (environment variable / secret manager), never in client-side code or a repo.

Each key belongs to one tenant. It can only ever read or modify data in that tenant — there is no cross-tenant access.

2. Authenticate

Send the key in the X-Api-Key header:

curl https://api.signward.com/api/users \
  -H "X-Api-Key: $SIGNWARD_API_KEY"

Use X-Api-Key, not Authorization: Bearer. API keys are sent in the X-Api-Key header. The Authorization: Bearer header is reserved for end-user OIDC access tokens (JWTs) — putting an API key there returns 401, because the JWT validator tries to parse it as a token.

3. Scopes

A key carries scopes (not user roles). Read operations need the *:read scope; create/update/delete need *:write.

Resource Scopes What you can do
/api/users users:read, users:write List/read users; create, update, delete; read (users:read), upload and remove a user's avatar; generate a new password (emailed to the user); reset / require MFA; resend verification
/api/roles roles:read, roles:write List/read custom roles; create, update, delete; assign / unassign a role to a user
/api/branding branding:read, branding:write Read / update tenant branding (colors, logo, favicon, custom CSS)
/api/webhooks webhooks:read, webhooks:write List/read webhook subscriptions; create, update, delete; send a test delivery; read delivery history
/api/auditlogs audit:read Read the tenant audit log (entries, stats, alerts, export). Read-only

4. Examples

List and create users:

# List (users:read)
curl https://api.signward.com/api/users \
  -H "X-Api-Key: $SIGNWARD_API_KEY"

# Create (users:write)
curl -X POST https://api.signward.com/api/users \
  -H "X-Api-Key: $SIGNWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.com","firstName":"Jane","lastName":"Doe"}'

Update a user, set an avatar, rotate a password:

# Update profile fields (users:write)
curl -X PUT https://api.signward.com/api/users/{userId} \
  -H "X-Api-Key: $SIGNWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","lastName":"Smith"}'

# Upload avatar — multipart, JPG/PNG/WebP, max 2 MB (users:write)
curl -X POST https://api.signward.com/api/users/{userId}/avatar \
  -H "X-Api-Key: $SIGNWARD_API_KEY" \
  -F "file=@avatar.png"

# Read avatar — returns the image bytes (users:read)
curl https://api.signward.com/api/users/{userId}/avatar \
  -H "X-Api-Key: $SIGNWARD_API_KEY" --output avatar.png

# Generate a new password — emailed to the user, not returned (users:write)
curl -X POST https://api.signward.com/api/users/{userId}/generate-password \
  -H "X-Api-Key: $SIGNWARD_API_KEY"

Assign a role and read the audit log:

# Assign role to user (roles:write)
curl -X POST https://api.signward.com/api/roles/{roleId}/users/{userId} \
  -H "X-Api-Key: $SIGNWARD_API_KEY"

# Read audit log (audit:read)
curl https://api.signward.com/api/auditlogs \
  -H "X-Api-Key: $SIGNWARD_API_KEY"

5. Errors

Status Body error Cause
401 — Missing or invalid API key
403 API key missing required scope: users:write The key lacks the scope for this operation
403 Write operations are not allowed on this resource via API key The resource is read-only for keys (e.g. audit)
403 This endpoint is not accessible via API key The path is not part of the Management API

All errors follow RFC 7807 Problem Details; include the traceId when contacting support.

What you can't do with an API key

By design, these are not on the Management API:

  • End-user self-service — sign-in, password reset, MFA enrollment, and a user editing their own profile happen on the hosted pages.
  • OIDC client and API-key administration — managing OIDC clients and issuing API keys is done in the Portal (a key can't mint more keys).
  • Billing / subscription and platform-operator operations.

Security notes

  • Tenant isolation is enforced server-side: a key only ever affects its own tenant.
  • Least privilege — a users:write key can manage every user in the tenant (create, delete, rotate passwords). Scope keys narrowly and rotate them if leaked.
  • Every Management-API change is written to the audit log.

Next