Getting started

Authentication

Every API request authenticates with an API key on the Authorization header. Keys carry an environment (live/test) and a set of scopes; the service enforces both on every call.

API keys

Send your secret key as a bearer token. The service computes a salted hash of the key, looks up the active consumer, and resolves its scopes and environment.

Authorization: Bearer sk_test_8f4c...c2

There are two key kinds across two environments:

sk_live_<40 base62>   # secret key, live mode  — server-side only
sk_test_<40 base62>   # secret key, test mode  — server-side only
pk_live_<40 base62>   # publishable key, live  — safe for clients
pk_test_<40 base62>   # publishable key, test

Secret keys (sk_) are full-access credentials. Keep them server-side; never ship them to a browser or mobile app.
Publishable keys (pk_) are safe to expose in clients for limited, public operations.
Test vs live. A test key sees only test-mode data; a live key sees only live data. They are never interchangeable, so you can build safely against test mode.

Heads up

A raw secret is returned once, at creation or rotation. Settla stores only a salted SHA-256 hash plus the prefix and last four characters for display — it can never show you the secret again. If a key leaks, rotate it (POST /v1/api-keys/:id/rotate), which revokes the old key and mints a new one.

Scopes

Each key carries a list of scopes. Endpoints check the required scope before doing any work; a missing scope returns 403 permission_error. The resolver, for example, requires resolve (or *). Grant the narrowest set a key needs.

Scope	Grants
resolve	Call POST /v1/resolve and /v1/resolve/bulk.
recommend_route	Call POST /v1/recommend-route (V2 routing).
identities:read	Read identities, masked alias/endpoint lists, usage.
identities:write	Create and update identities.
aliases:write	Register, update, and release aliases.
endpoints:write	Add, update, and remove endpoints.
verifications:write	Start and confirm proof-of-control challenges.
consent:read / consent:write	Read or grant/revoke consent grants.
routes:write	Manage a recipient's route policies.
webhooks:write	Create, update, and delete webhook endpoints.
keys:write	List, rotate, and revoke API keys.
directory:read / paylinks:write	Search the public directory; create payment links (V3).
*	All scopes (owner / admin keys).

Idempotency

All mutating (POST) requests accept an Idempotency-Key header — a unique client-generated value (a UUID works well). Settla stores the first response for that key and replays it on retries, so a network blip never creates a duplicate identity, alias, or endpoint.

curl https://api.settla.network/v1/identities \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: 5f0c2c8a-1b9e-4f3a-9c7d-2a1b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{"type":"user","display_name":"John"}'

Re-sending the same key with an identical body replays the stored response. Re-sending the same key with a different body returns 409 conflict_error.

Rate limits

Requests are rate-limited per key using a token bucket, with separate budgets per endpoint class (management, registry reads/writes, verification, admin). When a bucket is drained you get 429 rate_limit_error with standard headers so you can back off precisely.

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 7
Retry-After: 7
Content-Type: application/json

{ "error": { "type": "rate_limit_error", "code": "rate_limited",
  "message": "Too many requests. Retry after the reset window.",
  "request_id": "req_..." } }

Header	Meaning
RateLimit-Limit	Maximum requests allowed in the current window.
RateLimit-Remaining	Requests left before the bucket drains.
RateLimit-Reset	Seconds until the bucket refills.
Retry-After	Seconds to wait before retrying (sent on 429).

Note

The resolver also enforces an anti-scraping breadth quota — a cap on the number of distinct aliases a key may resolve per day (default 1,000). Exceeding it returns 429 scraping_quota_exceeded. This is separate from the velocity rate limit and protects the directory from enumeration.