API reference

The endpoints your application calls to integrate Signward — OIDC, token validation, and webhooks.

This reference covers the endpoints an integrating application uses to talk to Signward: the OIDC sign-in flow, token validation, webhooks, and the server-to-server Management API. End-user self-service — sign-up, password reset, MFA enrollment, passkey (WebAuthn) sign-in, and a user editing their own profile — happens on Signward's hosted pages; your app doesn't implement those.

The Signward API base URL is https://api.signward.com.

OIDC endpoints

Standards-compliant OpenID Connect 1.0 + OAuth 2.1 (PKCE mandatory, S256 only). The full conversation your app has with Signward.

Endpoint Purpose
GET /.well-known/openid-configuration Discovery document. Every OIDC library starts here.
GET /.well-known/jwks.json JSON Web Key Set — used by your backend to validate access-token signatures.
GET /connect/authorize Authorization Code flow entry. Your app redirects here; Signward sends the user to the tenant login page and redirects back with a code.
POST /connect/token Exchange the authorization code or a refresh_token for access_token / id_token / refresh_token.
GET /connect/userinfo Bearer-protected. Returns canonical user claims — sub, tenant_id, email, roles, given_name, family_name.
POST /connect/revoke RFC 7009 token revocation. Call this on sign-out.
POST /connect/introspect RFC 7662 token introspection (optional — most integrations validate locally via JWKS).
GET /connect/endsession End the Signward session and redirect the user to post_logout_redirect_uri.

Minimum integration

A server-rendered web app or SPA typically uses only three of these at runtime:

  1. /connect/authorize — redirect the user here to sign in
  2. /connect/token — exchange the returned code for tokens
  3. /connect/userinfo or the id_token claims — get the user identity

Plus /.well-known/openid-configuration + /.well-known/jwks.json once at startup to discover URLs and cache public keys.

Access token format

Signward-issued access tokens are RS256-signed JWTs carrying:

Claim Meaning
iss Always https://api.signward.com.
aud Your API audience (configured on the OIDC client).
sub The authenticated user's UUID.
tenant_id The tenant UUID. Use this to scope DB queries in your backend.
email User email.
roles Array — built-in (owner / admin / user) and custom roles defined in the Portal.
exp, iat, nbf, jti Standard JWT lifecycle claims.

Your backend should validate: signature (via JWKS), iss, aud, and expiration. The .NET SDK does this automatically; see Protect a Web API for the FastAPI recipe.

Management API (server-to-server)

For back-office and automation that acts on the tenant without a signed-in user, Signward exposes a machine-to-machine Management API authenticated with an API key (create keys in the Portal → API keys). Send the key in the X-Api-Key header (not Authorization: Bearer — that header is for end-user OIDC access tokens). Access is gated by the scopes granted to the key. See the Management API guide for end-to-end examples.

Resource Scopes What you can do
/api/users users:read, users:write List/read users; create, update, delete; read / upload / remove a user's avatar; generate a new password (emailed to the user); reset / require MFA; resend verification
/api/roles roles:read, roles:write Manage custom roles and user↔role assignments
/api/webhooks webhooks:read, webhooks:write Manage webhook subscriptions
/api/branding branding:read, branding:write Read / update tenant branding (colors, logo, custom CSS)
/api/auditlogs audit:read Read the tenant audit log

Every Management-API call is tenant-scoped to the key's tenant — a key can never read or modify another tenant. Grant only the scopes a key needs (least privilege): a users:write key can manage every user in its tenant.

Self-service vs. management. These endpoints act on other users (admin / automation). An end user changing their own profile, avatar, password, MFA or consent does that on the hosted pages — your app redirects them there; those are not API calls.

Webhooks

If your integration needs to react to tenant events server-to-server (new user signed up, invoice paid, user logged in, etc.), subscribe to webhooks. Webhook subscriptions themselves are managed in the Portal UI; the listening endpoint is yours to implement.

See the Webhooks guide for signature verification and the full event catalog.

Rate limits

Every response carries:

  • X-RateLimit-Limit — requests allowed in the current window
  • X-RateLimit-Remaining — requests left
  • X-RateLimit-Reset — epoch seconds when the window resets
  • Retry-After — seconds to wait after a 429

Defaults and plan overrides are in Reference → Rate limits.

Error format

All 4xx / 5xx responses follow RFC 7807 Problem Details:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-abc-def-00"
}

Include the traceId when opening a support ticket.

What's not here

These happen on Signward's hosted pages, not via the API:

  • End-user auth flows: sign-up, sign-in form, password reset, email verification, MFA enrollment, backup-code issuance, passkey sign-in
  • An end user's own self-service: profile / avatar / password / MFA / consent / GDPR data export
  • Billing and subscription management
  • Platform-operator dashboards

Your app redirects end users to https://{subdomain}.signward.com for these. Tenant admins use the Portal at https://portal.signward.com — but most tenant-admin operations (users, roles, branding, webhooks, audit) are also available server-to-server via the Management API with an API key.