Authentication

API keys

All API requests require an API key in the Authorization header:

Authorization: Bearer sk_live_<tenant>_<key>

Keys are scoped — each key carries a set of permissions (e.g. payment:read, customer:write). The required scope is documented on each endpoint.

Key format

Prefix	Environment
sk_live_	Production
sk_test_	Test / sandbox

Obtain keys from the dashboard under Settings → API Keys.

OAuth 2.0 (PKCE)

For third-party integrations, FinStack supports OAuth 2.0 authorization code flow with PKCE (S256 only).

Flow

1. Redirect user to /oauth/authorize with code_challenge (S256)
2. User authorizes — FinStack issues an authorization code
3. Exchange code + code_verifier for an access token at /oauth/token
4. Use the access token as Bearer in subsequent requests

Endpoints

Method	Path	Description
GET	/oauth/authorize	Issue authorization code
POST	/oauth/token	Exchange code for access token
POST	/oauth/revoke	Revoke a token
POST	/oauth/introspect	Validate a token

Security notes

• code_challenge_method must be S256 — plain PKCE is rejected
• Authorization codes expire in 10 minutes, single-use
• Access tokens expire in 1 hour

Webhooks

FinStack signs outbound webhooks with HMAC-SHA256. Verify the X-FinStack-Signature header on every inbound event. See the webhooks guide.