API And SDKs¶
Use SigID's APIs and SDKs to add login, protect APIs, manage tenant resources, and integrate agent workflows.
Choose an integration path¶
| Goal | Start with | Primary docs |
|---|---|---|
| Add login to a browser app | Authorization Code with PKCE | Applications And OAuth |
| Protect a backend API | Token validation and scopes | Security |
| Build a tenant dashboard integration | Control-plane APIs | Admin Operations |
| Manage users | Tenant user APIs | User Management |
| Add organizations and SSO | Organization and domain APIs | Organizations And SSO |
| Authenticate an agent | Agent identity anchors or client credentials | AI Agents |
| Let an agent act for a user | Token exchange | AI Agents |
| Connect third-party tools | Vault grants | AI Agents |
| Receive events | Webhooks | Webhooks And Events |
Agent-friendly application registration¶
Use @sigid/init when a coding agent or CLI workflow needs to create a local
development OAuth application without opening the dashboard:
npm exec @sigid/init -- \
--issuer https://auth.example.com \
--tenant acme \
--registration-token "$SIGID_DCR_INITIAL_ACCESS_TOKEN" \
--origin http://localhost:3000
The CLI calls /oauth/register, writes .env.local, and exits without creating
a duplicate client when SIGID_CLIENT_ID already exists. Multi-tenant tenant
selection requires Dynamic Client Registration to be protected by an initial
access token.
Integration architecture¶
Most production applications use three layers:
| Layer | Responsibility |
|---|---|
| Frontend | Starts login, handles callback, displays user state |
| Backend | Exchanges codes, validates tokens, enforces scopes, stores sessions |
| Event receiver | Processes webhook deliveries and synchronizes asynchronous state |
Avoid building authorization decisions only in the frontend. Frontends can render hints, but backend services must enforce access.
Frontend SDKs and examples¶
Frontend SDKs should make the browser experience predictable: redirect users, handle callbacks, expose session state, and request additional scopes when a feature needs them.
| Stack | What it is for |
|---|---|
| TypeScript client | Core browser and frontend integration |
| React | React applications |
| Vue | Vue applications |
| Solid | Solid applications |
| Svelte | Svelte applications |
| Next.js | Server-rendered React applications |
| SvelteKit | SvelteKit applications |
| SolidStart | SolidStart applications |
| Expo | React Native mobile apps |
| Electron | Desktop applications |
Frontend responsibilities:
- start Authorization Code with PKCE
- preserve and verify
state - handle callback errors
- request only needed scopes
- send API requests through your backend when secrets or privileged operations are involved
Backend SDKs¶
Backend SDKs help validate tokens and call SigID APIs from server-side code.
| SDK | Use case |
|---|---|
| Go | Backend services and infrastructure tooling |
| Rust | Rust services and security-sensitive integrations |
| Elixir | Phoenix and BEAM services |
Backend responsibilities:
- exchange authorization codes securely
- validate access tokens
- check scopes and tenant context
- manage application sessions
- call tenant administration APIs
- verify webhook signatures
- store secrets outside source code
API authorization model¶
APIs should enforce authorization following the sequence in Applications And OAuth.
Example access rule:
Request: DELETE /projects/{id}
Required audience: https://api.example.com
Required scope: projects:delete
Subject type: human or delegated agent
Policy: fresh MFA for human; explicit delegation for agent
Tenant: project.tenant_id must match token tenant
Idempotency¶
Use idempotency keys for write operations that a client may retry after a network failure. This is especially important for provisioning, invitations, webhook tests, device codes, dynamic client registration, billing, and ownership transfers.
Recommended client behavior:
- generate a stable key per intended operation
- reuse the key for retries of the same operation
- do not reuse a key for a different payload
- log idempotency keys in your client traces
Webhooks¶
Webhooks let tenants receive event notifications for user, application, billing, agent, wallet, and audit workflows. Always verify the webhook signature before processing the event.
See Webhooks And Events for receiver requirements, signature verification, and delivery handling.
API security expectations¶
- Validate tokens on the backend.
- Check scopes before serving protected resources.
- Store tenant IDs explicitly in your data model.
- Treat user subjects as tenant-local.
- Distinguish users, agents, services, and delegated subjects.
- Verify webhook signatures.
- Rotate client secrets if exposed.
- Avoid logging access tokens, refresh tokens, webhook secrets, or vault credentials.
Release checklist¶
Before shipping an integration:
- login works in each supported browser and platform
- callback error states are user-friendly
- token validation fails closed
- scopes are documented by feature
- logout and refresh behavior are tested
- user suspension blocks access
- organization context is enforced where needed
- webhook receiver handles retries and duplicates
- logs contain request IDs but not secrets
- support has a runbook for common failures