API Authentication
Apr 5, 2026 · 454 views
Every OneSigner API endpoint (except the public ones) requires a token. This page explains the token types and how to present them.
Presenting the Token
Bearer header (recommended)
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:9440/api/listQuery parameter (for tools that can't set headers)
curl "http://localhost:9440/api/list?token=YOUR_TOKEN"Prefer the header — query strings tend to end up in logs.
Token Types
| Token | Scope | Where configured |
|---|---|---|
| Admin token | Everything: signing management, profiles, tenants, status, AKV proxy | Tenants tab (Admin Token) |
| Tenant token | That tenant's own uploads, downloads, listing, signing | General tab (default tenant) / Tenants tab |
| Partner signing code | Only remote code-signing via the AKV proxy (-kva) | SigningEngine → AKV Proxy profile → Partner codes |
Admin Token
- Full access, including
/api/signing/*,/api/tenants,/api/reload-config. - Keep it off build machines — use tenant tokens or partner codes there.
Tenant Token
- Scoped to the tenant's upload/signed folders: upload, list, download, delete, sign.
- Uploads authenticated with a tenant token auto-match that tenant's signing profiles.
- Perfect for giving each client, department or pipeline its own isolated credential.
Public Endpoints (No Auth)
GET /— service status page- eSign signer ceremony links (
/portal/esign/<token>) — secured by their own single-purpose tokens and optional access codes - Demo endpoints, when enabled
Best Practices
- Generate long random tokens (the GUI's Generate button does this) — never reuse passwords.
- One token per consumer, so you can rotate or revoke without breaking everyone.
- Expose the API externally only via HTTPS (built-in Cloudflare Tunnel or your own reverse proxy).
- Rotate tokens when staff or vendors change; update the profile/tenant and reload config (
POST /api/reload-config).