---
summary: Reference SigID API surfaces, SDK packages, example apps, request rules, retries, errors, and integration safety.
tags:
  - api
  - sdks
  - developers
  - integration
categories:
  - Reference
---

# API And SDK Reference

<!-- agent:page
You are an AI agent using this reference to choose SigID API surfaces, SDK packages, and example apps, and to apply the cross-API request rules.
- Use the exact base paths in the API surfaces table (`/oauth/*`, `/auth/*`, `/api/v1/*`, `/api/v1/control-plane/*`, `/scim/v2/*`) and the exact package names (`@sigid/client`, `@sigid/next`, and the others listed); do not invent packages or routes.
- For exact request and response shapes, use the deployment's `/openapi.json` when enabled; this page is the map, not the schema.
- Apply the request rules everywhere: same-environment values, `idempotency-key` on retryable writes, `x-request-id` logging, and `Retry-After` on `429`.
- Match failures against the `application/problem+json` error class table before changing code.
- Never log access tokens, refresh tokens, client secrets, webhook secrets, MFA codes, or vault credentials.
- For the login procedure see Add SigID Login; for token validation see Verify Tokens; for events see Webhook Events.
-->

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](../developers/sdks-examples.md).

## 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](../developers/add-login.md). For OAuth and OIDC
behavior, read [OAuth And OIDC](oauth-oidc.md).

## On This Page

- [Before you start](#before-you-start)
- [Choose an integration path](#choose-an-integration-path)
- [API surfaces](#api-surfaces)
- [OpenAPI reference](#openapi-reference)
- [TypeScript and framework SDKs](#typescript-and-framework-sdks)
- [Backend SDKs](#backend-sdks)
- [Example apps](#example-apps)
- [Request rules](#request-rules)
- [Security rules](#security-rules)

## 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](../developers/add-login.md) | [OAuth And OIDC](oauth-oidc.md) |
| Protect a backend API | [Verify Tokens](../developers/verify-tokens.md) | [OAuth And OIDC](oauth-oidc.md) |
| Use a frontend framework SDK | [TypeScript and framework SDKs](#typescript-and-framework-sdks) | Matching example app |
| Use a backend SDK | [Backend SDKs](#backend-sdks) | [OpenAPI reference](#openapi-reference) |
| Manage tenant users | [Users And Login Methods](../business/users-login-methods.md) | [Request rules](#request-rules) |
| Manage organizations, SSO, or SCIM | [Organizations And SSO](../business/organizations-sso.md) | [Request rules](#request-rules) |
| Receive signed events | [Webhook Events](webhook-events.md) | [Security rules](#security-rules) |
| Build agent or MCP integration | [Agent And MCP Auth](../developers/agents-mcp.md) | [OAuth And OIDC](oauth-oidc.md#device-authorization-ciba-and-token-exchange), [Claims And Scopes](claims-and-scopes.md#delegation-claims) |

## 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:

```text
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

<!-- agent:action Set up a TypeScript client
Install `@sigid/client` and create the client with `createSigIdClient`, supplying the issuer `baseURL`, public `clientId`, registered `redirectUri`, and minimal scopes.
- wire `sigid.login()` to the login action, `sigid.handleCallback()` on the callback route, and `sigid.logout()` to an explicit user action
- prefer the framework package that matches the runtime (`@sigid/next`, `@sigid/sveltekit`, `@sigid/react`, ...) over hand-rolled glue
- use only public packages; `@sigid/frontend-*` packages are internal
-->

Install the framework-agnostic client:

```bash
npm install @sigid/client
```

Create a hosted-login client:

```typescript
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:

```typescript
const session = await sigid.handleCallback();
```

On a logout button or explicit user action:

```typescript
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

<!-- agent:action Call a tenant API
Send tenant-scoped requests to `$SIGID_ISSUER_URL/api/v1/...` with `authorization: Bearer $ACCESS_TOKEN` from the same environment as the issuer and tenant.
- add an `idempotency-key` header on retryable writes such as webhook creation
- when creating a webhook without `secret`, store the generated signing secret immediately; it is returned only once
- log resource, tenant, and request IDs, never the bearer token
-->

Tenant-scoped API calls use bearer tokens:

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

Use idempotency keys for retryable writes:

```bash
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

<!-- agent:action Handle API error classes
Parse `application/problem+json` responses and branch on the `error` field plus HTTP status using the class table.
- restart the OAuth flow on `invalid_grant`; re-authenticate on `401 unauthorized`; check client auth on `invalid_client`
- request the missing scope on `insufficient_scope`; check tenant context and policy on `403 forbidden`
- respect `Retry-After` on `429`; retry `5xx` only with an idempotency key
- record `x-request-id` for support, and never log tokens or secrets
-->

SigID API errors use `application/problem+json`. Responses include RFC 7807
fields and OAuth-compatible fields:

```json
{
  "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

- [Add SigID Login](../developers/add-login.md) for the first local login flow
- [OAuth And OIDC](oauth-oidc.md) for OAuth/OIDC behavior and grant selection
- [Verify Tokens](../developers/verify-tokens.md) for backend authorization requirements
- [Webhook Events](webhook-events.md) for signed event receivers
- [Agent And MCP Auth](../developers/agents-mcp.md) for the agent integration overview
- [OAuth And OIDC](oauth-oidc.md#device-authorization-ciba-and-token-exchange) for delegated token-exchange patterns
- [Agent And MCP Auth](../developers/agents-mcp.md) for MCP and tool authorization boundaries
- [Users And Login Methods](../business/users-login-methods.md) for user lifecycle and tenant membership
- [Organizations And SSO](../business/organizations-sso.md) for B2B organizations, SSO, and directory provisioning