Authentication
Every request except the health check carries a key. Keys identify an organisation rather than a user, and carry that organisation's plan and quota.
The header
curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
-H "X-API-Key: sk_live_9f21c4a70b8e…"
# Authorization: Bearer works too, for clients that make it the easy path.
curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
-H "Authorization: Bearer sk_live_9f21c4a70b8e…"Either header works. If both are present, X-API-Key wins. A missing or
malformed header returns 401 with an authentication_required code, and the
response never says whether the key does not exist or has been revoked:
distinguishing those would let somebody probe for valid keys.
Key kinds
| Prefix | Kind | What it does |
|---|---|---|
sk_live_ | Live | Reads and writes real inventory. Rate limited against your plan quota. |
sk_test_ | Test | Reads a small fixed dataset and accepts writes that are discarded. Free, and generously rate limited, so integration tests need not burn quota. |
The prefix is part of the key, so a leaked string is recognisable as a Skautik credential in a log or a repository scan. That is deliberate: secret scanners can match on it and alert you before somebody else finds it.
Scopes
Scopes are per resource rather than a blanket read and write pair. A key is created with the set it needs, and the API refuses any call whose key lacks the scope that route requires.
Grant the narrowest set that does the job. A key issued for market analysis cannot then read anybody's contact details or withdraw a listing, however badly it leaks.
| Scope | Permits |
|---|---|
properties:read | Read properties and their media. |
properties:write | Create, update, and withdraw properties. |
markets:read | Read market statistics and intelligence. |
imports:write | Submit and manage bulk imports. |
exports:create | Request exports and download the results. |
images:write | Generate and attach rendered images. |
webhooks:manage | Create, update, and delete webhook endpoints. |
inquiries:read | Read enquiries submitted against your properties. |
Rotation
Keys do not expire on a schedule, because forced expiry tends to produce an outage rather than better security. Rotate deliberately instead. An organisation can hold several keys at once precisely so this needs no downtime:
- Create a second key alongside the one in use.
- Deploy it to your services and confirm traffic has moved to it.
- Check the old key has gone quiet on the keys page, rather than assuming it has.
- Revoke the old key.
Revocation takes effect immediately, with no grace period.
Keeping a key secret
- Server-side only. A key shipped to a browser or a mobile binary is a key published, regardless of obfuscation. Proxy through your own backend.
- Keep keys in environment variables or a secret manager, never in a repository, a build artefact, or a client bundle.
- Use a separate key per environment and per service, so revoking one does not take everything down with it.
- The full key is shown once at creation and stored only as a hash. We cannot recover it for you; create a new one instead.
If a key leaks
Revoke it first and investigate afterwards: a revoked key costs you a deployment, an active leaked one costs you your quota and your data.
Then email security@skautik.com so we can check for use you did not make. We also monitor public code hosts for our key prefixes and will revoke a key we find exposed, telling you when we do.
Checking a key
GET /v1/api/me reports the organisation, plan, and remaining quota behind a
key. It is the right call for a startup check or a health probe, because it
proves the key works without paging a resource.
Manage keys from the API keys page.