API reference

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

This reference lists only the endpoints an integrating application needs to talk to Signward at the API level. Everything else — user sign-up, password reset, MFA enrollment, profile editing — happens on Signward's hosted pages and in the Portal. Your app doesn't implement them.

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.

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

Operations that the Portal and the Signward hosted pages cover — not API integration concerns:

  • User sign-up, sign-in form, password reset, email verification
  • MFA enrollment, backup-code issuance, MFA disable
  • Profile updates, avatar upload, consent management, GDPR data export
  • Tenant administration (adding users, editing branding, billing, audit log viewer)
  • Platform-operator dashboards

Your app redirects users to https://{subdomain}.signward.com for anything user-facing, and to https://portal.signward.com for tenant admin.