Getting Started

Authentication

Calibr supports two authentication methods: JWT bearer tokens for interactive sessions and API keys for programmatic access. Choose the method that fits your integration.

JWT Bearer Token

JWT tokens are used by the Calibr desktop app and the web dashboard. They are obtained by authenticating with your email and password via the POST /api/auth/login endpoint. Tokens expire after 1 hour and are automatically refreshed using a long-lived refresh token.

Obtaining a token

curl -X POST https://api.calibr.dev/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "analyst@yourbank.com", "password": "your-password" }'

Response:

json

{ "access_token": "eyJhbGciOiJIUzI1NiIs...", "refresh_token": "dGhpcyBpcyBhIHJlZnJl...", "expires_in": 3600, "token_type": "Bearer" }

Using the token

Pass the access token in the Authorization header of every request:

curl https://api.calibr.dev/api/v1/scorecards \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Refreshing tokens

When an access token expires, use the refresh token to obtain a new one without re-entering credentials:

curl -X POST https://api.calibr.dev/api/auth/refresh \ -H "Content-Type: application/json" \ -d '{ "refresh_token": "dGhpcyBpcyBhIHJlZnJl..." }'

API Key

API keys are designed for server-to-server integrations such as loan origination systems, decision engines, and batch scoring pipelines. They do not expire but can be revoked at any time.

Keys follow a prefixed format so you can identify the environment at a glance:

sk_live_xxxx — production keys, used for real scoring decisions
sk_test_xxxx — staging keys, used for testing and development

Create API keys from the web dashboard under Settings → API Keys, or from the Calibr desktop app under Settings → API.

Using an API key

curl https://api.calibr.dev/api/v1/score \ -H "Authorization: Bearer sk_live_abc123def456" \ -H "Content-Type: application/json" \ -d '{ "scorecard_id": "sc_01HXYZ", "applicant": { "monthly_income": 5500, "employment_length": 36, "debt_to_income": 0.28 } }'

Scopes

API keys can be scoped to limit what actions they can perform. Assign only the scopes your integration needs.

Scope	Permits	Typical Use
`score`	Submit scoring requests	Loan origination systems
`deploy`	Deploy and manage scorecards	CI/CD pipelines
`read`	Read scorecards, logs, and analytics	Monitoring dashboards
`admin`	Full access including team management	Admin tooling

Security Best Practices

Never expose API keys in frontend code. Keys should only be used in server-side environments. If a key is compromised, revoke it immediately from the dashboard.
Rotate keys regularly. Create a new key, update your integration, then revoke the old key. Calibr supports multiple active keys to make rotation seamless.
Use the narrowest scope possible. A scoring endpoint only needs the score scope. Do not grant admin unless strictly necessary.
Use test keys for development. The sk_test_ prefix ensures requests never touch production data.
Store keys in environment variables or a secrets manager. Never commit keys to version control.