Authentication
stile uses two types of keys — publishable keys for your frontend and secret keys for your server.
Key types
stile uses two types of API keys, each with a specific purpose:
| Key type | Prefix | Where to use | Purpose |
|---|---|---|---|
| Publishable key | pk_test_... / pk_live_... | Frontend (safe to expose) | Used by the widget to create verification sessions on behalf of your users. |
| Secret key | vk_test_... / vk_live_... | Server only (never expose) | Full API access — create sessions, manage webhooks, read events, and verify webhook signatures. |
Both key types come in test and live variants:
- Test keys — for development. No real verifications are processed, and no real identity documents are checked.
- Live keys — for production. Real identity verification is performed.
Create and manage your keys in the dashboard.
Keep secret keys on your server
Secret API keys (vk_test_ / vk_live_) grant full access to your organization. Never commit them to source control, include them in frontend code, or log them. Store them in environment variables. Publishable keys (pk_test_ / pk_live_) are safe to include in your HTML.
Making API requests
Pass your secret key in the Authorization header as a Bearer token:
curl https://api.stile.dev/v1/verification_sessions \
-H "Authorization: Bearer vk_test_YOUR_API_KEY" \
-H "Content-Type: application/json"With the Node.js SDK, set the key once — it's sent automatically with every request:
import Stile from "@stile/node";
const stile = new Stile(process.env.STILE_API_KEY!);You may not need the API directly
If you're using the widget with a publishable key, you don't need to make API calls yourself — the widget handles session creation automatically. The API is for advanced use cases like server-side session management, reading events, or managing webhook endpoints programmatically.
Rate limits
Requests are rate-limited per API key on a per-minute rolling window.
| Key type | Limit |
|---|---|
vk_test_... | 100 req / min |
vk_live_... | 1,000 req / min |
Every response includes rate limit headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1741564920 # Unix timestamp of window resetWhen you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait. See the error handling guide for more details.
Rotating keys
To rotate a key, go to the dashboard and:
- Create a new key
- Copy the secret and update your environment variables
- Redeploy your application
- Revoke the old key
The new key's secret is only shown once at creation — store it in your secrets manager immediately.