Authentication

FundOS supports OAuth 2.0 PKCE for interactive agents and Bearer API keys for headless server-side access. Both paths produce the same tool access — the difference is how credentials are obtained.

OAuth 2.0 PKCE (recommended)

OAuth is the recommended method for Claude Code and any agent that runs interactively with a human in the loop. The user approves access once; the token is refreshed automatically.

Discovery endpoints

Endpoint	Description
`/.well-known/oauth-authorization-server`	Authorization server metadata (RFC 8414)
`/.well-known/oauth-protected-resource`	Protected resource metadata (RFC 9728)
`/oauth/authorize`	Authorization endpoint
`/oauth/token`	Token endpoint

Flow overview

# 1. Generate PKCE verifier + challenge
code_verifier=$(openssl rand -base64 32 | tr -d '+/=' | head -c 43)
code_challenge=$(echo -n "$code_verifier" | sha256sum | xxd -r -p | base64 | tr -d '=' | tr '+/' '-_')

# 2. Redirect user to authorization URL
https://kela.com/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-agent.example.com/callback
  &scope=read
  &code_challenge=$code_challenge
  &code_challenge_method=S256

# 3. Exchange code for tokens
curl -X POST https://kela.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://your-agent.example.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=$code_verifier"

Scopes

Scope	Access
`read`	All read tools (read_fast, read_multi, read_compute)
`write`	Read + write tools (creates proposed actions for human approval)
`ai`	Read + AI-heavy tools (VDR analysis, ODD, CIM generation)

Request only the scope your agent needs. Most read-only workflows use read only.

Module-scoped tokens

You can restrict an OAuth client to specific FundOS modules by setting enabled_modules on the client record. For example, a law firm integration only needs the vdr and transactions modules:

{
  "client_id": "lawfirm-integration",
  "enabled_modules": ["vdr", "transactions"],
  "scope": "read write"
}

Tool calls for modules not in enabled_modules return 403 module_not_enabled.

API keys (Bearer token)

API keys are best for server-side scripts, CI pipelines, and automated agents that run without a human present.

Create a key

Go to FundOS → Admin → API Keys and click New API Key. The plaintext key is shown only once at creation — copy it immediately.

# Use in any API call
curl https://kela.com/api/v1/usage \
  -H "Authorization: Bearer vdr_YOUR_KEY_HERE"

Key format

All API keys start with the prefix vdr_ followed by 32 random hex characters. The server stores only a SHA-256 hash — the plaintext is never stored.

Key security: Never commit API keys to version control. Use environment variables (FUNDOS_API_KEY=vdr_…) or a secrets manager. Rotate keys at /admin/api-keys if compromised.

Token lifetimes

Token type	Lifetime	Refreshable
OAuth access token	1 hour	Yes — via refresh_token
OAuth refresh token	30 days	Yes — sliding window
API key	Until revoked	N/A

Credit deduction

Credits are only consumed by OAuth token requests (agents and API key users). Human browser sessions using the FundOS UI do not consume credits — they are covered by the subscription plan.

Revoking access

OAuth clients: Revoke at /admin/oauth/ — immediately invalidates all tokens for that client.
API keys: Delete at /admin/api-keys.
User-level: Deactivate the user account at /admin/users.