One of the core promises of a platform like smallstack is that it plays well with the rest of your stack. That means: a clean REST API, webhook support for external automation — and a way for external systems to authenticate without impersonating a user.
We recently shipped API key management for smallstack. Here's what we built, why, and how it works.
The Problem with User-Based Auth for Integrations
The old approach was simple but fragile: external integrations used session tokens tied to real user accounts. This works until it doesn't:
- The user leaves the company → integration breaks
- The user changes their password → integration breaks
- You want to audit what the integration did vs. what the user did → you can't
Service accounts help, but they're a workaround. What integrations actually need is a dedicated credential that:
- Isn't tied to a human user
- Can be scoped to specific permissions
- Can be rotated without affecting user sessions
- Shows up clearly in audit logs
That's an API key.
How It Works in smallstack
Creating a Key
API keys are created per project in the backoffice. Each key gets:
- A name (for identification in logs and the UI)
- A set of permission scopes (read, write, admin — per resource type)
- An optional expiry date
When you create a key, the full value is shown once and then never again. We store only a hashed version — the same pattern as password storage. If you lose it, you rotate.
Using a Key
Authentication uses the standard Authorization header:
GET /api/projects/{projectId}/contacts
Authorization: Bearer sk_live_abc123...
Keys are validated against the hashed store on each request. The key's scopes are checked against the required permission for the endpoint.
Scoping
Not every integration needs full access. A webhook receiver that only writes incoming form data doesn't need read access to all contacts. Scopes let you apply the principle of least privilege without creating multiple user accounts.
Rotation
Keys can be rotated from the backoffice without downtime. The workflow:
- Create a new key with the same scopes
- Update the external integration to use the new key
- Delete the old key
No service interruption. No shared credentials.
Design Decisions
Why not OAuth? OAuth is the right choice when the integration acts on behalf of a user, or when you need delegated consent flows. For machine-to-machine integrations (cron jobs, webhooks, data pipelines), API keys are simpler to implement and reason about. We may add OAuth for user-delegated access in the future.
Why not JWTs for keys? JWTs are great for session tokens — short-lived, stateless, self-contained. API keys have different requirements: they need to be revocable immediately (you can't revoke a JWT that hasn't expired), and you want to track usage per key. That requires a database lookup on validation, which means the statelessness of JWT isn't a win here.
Hashing the key value: The key value is generated on creation, shown once, and then stored only as a hash (bcrypt with appropriate cost). This means even if someone reads the database, they can't extract active keys. It also means we genuinely can't recover a lost key — which is the right behavior for a credential store.
Integration with smallstack's Action System
API keys work with the visual workflow automation too. You can configure an incoming webhook trigger with a specific API key — when an external system POSTs to that endpoint with a valid key, the workflow fires.
This means you can build integrations like:
- A form on your website submits to smallstack via webhook → triggers a contact creation and welcome email workflow
- A cron job hits a scheduled endpoint → triggers a data export workflow
- An external monitoring system sends alerts → creates incident records with automatic assignments
No Zapier. No middleware. Just a key and a webhook URL.
What's Next
A few things on the roadmap:
- Usage analytics per key — how many requests, which endpoints, last used timestamp
- IP allowlisting — restrict key usage to specific source IPs for high-security deployments
- Webhook signing — HMAC signatures on outbound webhooks so receivers can verify the payload came from smallstack
The API key system is live now. If you're building integrations on smallstack, you can create keys in your profile settings under API Keys.
Questions? Drop them in the comments or check the docs.
smallstack is a local-first business platform. You can build custom CRMs, project trackers, client portals, and workflows — without writing code. Developers can extend it with custom widgets and action blocks.
