API And SDK Reference¶

Use this reference to choose the right SigID API surface, SDK package, example app, and follow-up guide for your integration. For first-task onboarding, start with SDKs And Examples.

What this page is for¶

Start here when you need to:

• choose between OAuth, hosted auth, tenant APIs, SCIM, webhooks, and agent integrations
• pick the right TypeScript, framework, mobile, desktop, or backend SDK
• find a working example app for your runtime
• understand request, retry, error, and logging rules that apply across APIs

For a first login flow, start with Add Login To Your App. For OAuth and OIDC behavior, read OAuth And OIDC.

On This Page¶

• Before you start
• Choose an integration path
• API surfaces
• OpenAPI reference
• TypeScript and framework SDKs
• Backend SDKs
• Example apps
• Request rules
• Security rules

Before you start¶

Get these values from the tenant owner, administrator, or platform team:

Keep issuer, tenant, client ID, redirect URI, scopes, and audience from the same environment. Do not mix development, staging, and production values.

Choose an integration path¶

API surfaces¶

Use the protocol-specific guides for integration order and safety rules. Use the OpenAPI schema for exact request and response shapes.

OpenAPI reference¶

SigID splits OpenAPI into two exposures:

When enabled:

GET /openapi.json
GET {openapi.docs_path}   # Scalar UI, default /api/docs

Committed snapshots in the repository:

• openapi-public.json – public integrator document (regenerate via SIGID_WRITE_OPENAPI_PUBLIC=1 cargo test --no-fail-fast -p sigid-server --features openapi --lib routes::openapi::tests::public_document_excludes_control_plane_and_billing)
• openapi.json – historical full snapshot used for version lockstep; do not assume production serves it

Agents integrating third-party apps should use public OpenAPI + discovery, not the internal document. Commerce merchant admin routes are documented in Sell Access With SigID Commerce, not the public OpenAPI file.

TypeScript and framework SDKs¶

For agent identity, workspace bootstrap, and human delegation from Node.js/Bun, see the JavaScript Agent SDK (@sigid/agent; initial npm publication pending). It uses no native CLI executable.

Install the framework-agnostic client:

npm install @sigid/client

Create a hosted-login client:

import { createSigIdClient } from "@sigid/client";

export const sigid = createSigIdClient({
  baseURL: "https://auth.example.com",
  oauth: {
    clientId: "public-client-id",
    redirectUri: `${window.location.origin}/auth/callback`,
    scopes: ["openid", "profile", "email"],
  },
});

// Login button or "start login" action.
await sigid.login();

On the callback page or callback route:

const session = await sigid.handleCallback();

On a logout button or explicit user action:

await sigid.logout();

Use @sigid/next requireAccessToken() for protected API routes. The Next.js quickstart completes its OAuth callback in the browser; it does not require a catch-all auth proxy. Lower-level OAuth helpers createAuthorizationUrl(), exchangeCode(), and oauthSignOut() remain available for protocol-aware integrations.

For the complete TypeScript / Next.js reference path, see examples/sdk-lab-next.

Public TypeScript packages (only these exist today):

For browser frameworks without a SigID adapter, use @sigid/start or @sigid/client. There are no @sigid/vue, @sigid/solid, @sigid/solidstart, @sigid/expo, or @sigid/electron packages. Native and desktop integrations need an OAuth/OIDC library suited to their runtime; see SDKs And Examples.

Internal frontend packages such as @sigid/frontend-api-types, @sigid/frontend-config, and @sigid/frontend-ui support SigID apps in this repository. They are not the main public SDK entry points.

Backend SDKs¶

Backend SDKs are for server-side OAuth helpers, PKCE, code exchange, client credentials, UserInfo, and tenant-aware API calls. Use OpenAPI for exact resource schemas.

For languages without an official SDK, use the OpenAPI schema to generate a client or call the HTTP APIs directly.

Backend responsibilities:

• store state, PKCE verifiers, refresh tokens, and client secrets outside browser code
• exchange authorization codes with the registered token endpoint auth method
• validate access tokens before serving protected resources
• check tenant context, audience, and scopes
• call tenant, management, or SCIM APIs with the right bearer token
• verify webhook signatures in event receivers

Example apps¶

Use the example closest to your runtime:

Minimal API request¶

Tenant-scoped API calls use bearer tokens:

curl -sS "$SIGID_ISSUER_URL/api/v1/tenant-users" \
  -H "authorization: Bearer $ACCESS_TOKEN"

Use idempotency keys for retryable writes:

curl -sS "$SIGID_ISSUER_URL/api/v1/webhooks" \
  -X POST \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -H "idempotency-key: webhook-create-001" \
  -d '{
    "url": "https://api.example.com/webhooks/sigid",
    "event_types": ["auth.login.success", "tenant_user.suspended"]
  }'

If you omit secret, SigID generates a webhook signing secret and returns it only once. Store it immediately.

Request rules¶

Apply these rules across SigID API integrations:

• use bearer tokens for tenant APIs and management APIs
• use SCIM bearer tokens only for /scim/v2/*
• keep issuer, tenant, client, scope, and audience values from one environment
• send idempotency-key on retryable writes when the endpoint supports it
• preserve or log x-request-id values for support and incident triage
• respect Retry-After on 429 responses
• avoid retrying non-idempotent writes unless you supplied an idempotency key
• log resource IDs, tenant IDs, request IDs, and idempotency keys, but not secrets

Error handling¶

SigID API errors use the RFC 9457 application/problem+json shape. OAuth protocol endpoints return their protocol-defined error fields separately.

{
  "type": "https://sigid.org/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Bad request"
}

Handle these classes explicitly:

Log request IDs, tenant IDs, resource IDs, and idempotency keys. Do not log access tokens, refresh tokens, client secrets, webhook secrets, MFA codes, or vault credentials.

Rate-limit response headers¶

See the SigID Public API policy for RateLimit, RateLimit-Policy, Retry-After, structured JSON errors, and cross-origin header visibility. Quota fields follow IETF draft-11 Structured Fields syntax; they are not a published RFC.

Versioning And Deprecation¶

The stable public HTTP contract is URL-versioned under /api/v1/*. OAuth 2.1 and OpenID Connect endpoints keep their protocol-standard paths and evolve only within the compatibility rules of those protocols. Within a published API major version, SigID adds fields and operations compatibly; it does not silently change request shapes, response shapes, status codes, or error contracts.

When a stable operation or representation is deprecated, SigID documents the replacement in the OpenAPI description and changelog, then returns the HTTP Deprecation response header defined by RFC 9745. When a removal date is known, the response also carries Sunset and a Link with rel="deprecation" pointing to migration guidance. Removal of the old contract is reserved for the next major API version. Clients should record these headers in integration telemetry and schedule migration before the sunset date; they must not treat absence of a header as permission to ignore the published compatibility policy.

SigID's product releases follow Semantic Versioning. A product release and an API path version are related but not identical: compatible product releases may continue to serve /api/v1, while an incompatible public contract requires a new major API path and a product major release. The committed OpenAPI document is the canonical operation and schema inventory for the deployed product version.

Security rules¶

Before production:

• validate tokens before serving protected APIs
• check issuer, audience, signature, expiration, tenant context, and scopes
• store the validated sub claim with tenant context as the durable user key
• do not use email as a durable user ID
• never expose confidential client secrets in browser, mobile, or desktop code
• store client secrets, refresh tokens, webhook secrets, and SCIM tokens in a secret manager
• verify webhook signatures before parsing event business logic
• scope access tokens and management tokens to the smallest job that needs them
• treat agent and delegated access tokens as different from normal user sessions

Next steps¶

• Add SigID Login for the first local login flow
• OAuth And OIDC for OAuth/OIDC behavior and grant selection
• Verify Tokens for backend authorization requirements
• Webhook Events for signed event receivers
• Agent And MCP Auth for the agent integration overview
• OAuth And OIDC for delegated token-exchange patterns
• Agent And MCP Auth for MCP and tool authorization boundaries
• Users And Login Methods for user lifecycle and tenant membership
• Organizations And SSO for B2B organizations, SSO, and directory provisioning