Authentication

API Keys

The simplest way to authenticate. Get your key from the Developer Dashboard (self-service coming in v0.2) or email developers@soft.house for beta access.

Key Types

Prefix	Environment	Usage
Sandbox	No key required	Zero-friction evaluation (sandbox.api.soft.house)
sk_live_...	Live mode	Production (request via email beta access)

Using API Keys

Include your API key in the Authorization header:

curl https://api.soft.house/wishes \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE"

Or with the TypeScript SDK (coming soon — not yet on npm):

import { SoftHouse } from '@pragma/sdk-soft-house';

const soft = new SoftHouse({
  apiKey: process.env.SOFT_HOUSE_API_KEY,
});

OAuth 2.1

For user-facing applications, use OAuth 2.1 to let users authorize your app:

// Redirect user to authorization
const authUrl = soft.oauth.getAuthorizationUrl({
  client_id: 'your_client_id',
  redirect_uri: 'https://your-app.com/callback',
  scope: 'wishes:read wishes:write',
});

// Exchange code for tokens (in callback handler)
const tokens = await soft.oauth.exchangeCode({
  code: 'auth_code_from_callback',
  redirect_uri: 'https://your-app.com/callback',
});

Available Scopes

Scope	Access
wishes:read	Read wishes
wishes:write	Create and update wishes
mandates:read	Read mandates
mandates:write	Create mandates
payments:read	Read payment history

Security Best Practices

• Never expose API keys in client-side code
• Use environment variables for key storage
• Rotate keys regularly (90 days recommended)
• Use test keys during development
• Set up key permission scopes
• Enable webhook signature verification