Skip to content

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

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

Value Used for
SIGID_ISSUER_URL API base URL, discovery, OAuth endpoints, and hosted auth
Tenant ID or tenant slug Tenant isolation, support, logs, and troubleshooting
SIGID_CLIENT_ID OAuth requests and SDK configuration
Redirect URI Browser, mobile, desktop, and framework callback handling
Access token Calling tenant APIs, management APIs, or backend resources
Required scopes API authorization and least-privilege access
API audience Backend access-token validation
Token endpoint auth method OAuth token exchange for public or confidential clients
Webhook signing secret Receiver verification, if your integration consumes events

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

I need to... Start here Then read
Add login Add SigID Login OAuth And OIDC
Protect a backend API Verify Tokens OAuth And OIDC
Use a frontend framework SDK TypeScript and framework SDKs Matching example app
Use a backend SDK Backend SDKs OpenAPI reference
Manage tenant users Users And Login Methods Request rules
Manage organizations, SSO, or SCIM Organizations And SSO Request rules
Receive signed events Webhook Events Security rules
Build agent or MCP integration Agent And MCP Auth OAuth And OIDC, Claims And Scopes

API surfaces

Surface Base path Use Auth model
OAuth/OIDC /oauth/*, /.well-known/*, /userinfo Login, token exchange, discovery, JWKS, UserInfo OAuth client auth, bearer tokens, or public discovery
Hosted auth /auth/* Hosted sign-in, session, recovery, and account flows Browser session and OAuth flow state
Tenant APIs /api/v1/* Tenant-scoped applications, users, organizations, policies, agents, billing, and audit workflows where enabled Bearer token with tenant context and scopes
Control plane /api/v1/control-plane/* Platform-level tenant and instance operations Control-plane operator token
SCIM /scim/v2/* Directory provisioning for enterprise tenants where enabled SCIM bearer token
OpenAPI /openapi.json Machine-readable API schema when enabled Public only when the deployment exposes OpenAPI
Webhooks Your receiver URL Signed asynchronous events sent by SigID HMAC-signed delivery from SigID

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

OpenAPI reference

When OpenAPI is enabled by the deployment, use:

GET /openapi.json

Some deployments also expose an interactive OpenAPI UI from the OpenAPI router. Use the deployment's documented docs URL instead of assuming a fixed path such as /api/docs.

OpenAPI should be treated as a deployment-controlled surface. It may be disabled by default or unavailable in production environments.

TypeScript and framework SDKs

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 createAuthHandlers() for Next.js auth routes and requireAccessToken() for protected API routes. 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:

Package Use
@sigid/client Framework-agnostic browser, session, OAuth helper, and cookie utility integration
@sigid/react React hooks and session state
@sigid/vue Vue composables
@sigid/solid Solid primitives
@sigid/svelte Svelte stores
@sigid/next Next.js route handlers and server integration
@sigid/sveltekit SvelteKit hooks and server load integration
@sigid/solidstart SolidStart routes and server functions
@sigid/expo React Native / Expo storage and redirects
@sigid/electron Electron main/renderer authentication helpers

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.

SDK Directory Install Use
Go sdks/go go get github.com/sigid/sigid/sdks/go Go services, CLIs, and infrastructure tooling
Rust sdks/rust sigid-sdk = { git = "https://github.com/sigid/sigid", package = "sigid-sdk" } Rust services and security-sensitive integrations
Elixir sdks/elixir {:sigid, git: "https://github.com/sigid/sigid", sparse: "sdks/elixir"} Phoenix, BEAM services, and server-side integrations

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:

Example Demonstrates
examples/next-app Next.js route handler, server-side session, and protected page
examples/sveltekit SvelteKit hooks, server load, locals, and protected route
examples/solidstart SolidStart route handler, server data, and protected route
examples/expo Expo deep links, secure storage, OAuth flow, and protected screen
examples/electron Electron secure storage, IPC bridge, persistent session, and renderer isolation

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 application/problem+json. Responses include RFC 7807 fields and OAuth-compatible fields:

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

Handle these classes explicitly:

Class Developer response
400 bad_request Fix request shape, missing fields, or unsupported input
400 invalid_grant Restart the OAuth flow or refresh-token flow
400 invalid_scope Request scopes allowed by the application and tenant policy
401 unauthorized Re-authenticate or refresh token
401 invalid_client Check client authentication method and secret handling
403 forbidden Check tenant context, role, and policy
403 insufficient_scope Request a token with the required scope
404 not_found Check tenant context and resource ID
409 conflict Retry idempotently or refresh local state
429 rate_limited Respect Retry-After
5xx server_error Retry safely only with idempotency

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.

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