Get started

Quarzo provides a collection of APIs that enable you to integrate with our products and services. This guide will walk you through everything you need to make your first API call.

How it works

Our APIs accept and return JSON in the HTTP body and use standard HTTP response codes. You can consume them directly using any HTTP or REST library - no SDK required.

Authentication depends on what's calling the API: a broker backend authenticates as a service account, while a subscriber or broker user signing into your app authenticates through a federated login. See Authentication for both flows in full.

Glossary

The world of insurance has a rich vocabulary. We have put together a glossary to help you.

Glossary

Before you begin

You will need:

• A service-account JSON key for your broker backend, provisioned by Quarzo during onboarding - request a sandbox account if you don't have one yet

Sandbox environment

The sandbox lets you test API calls without affecting live data. All resources created there are isolated and will never appear in production.

Step 1 — Get a service-account access token

Build a JWT assertion signed with your service account's private key, and exchange it for an access token using the JWT Bearer Grant flow:

POST {authority}/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=<signed-jwt-assertion>
&scope=<scope-string-provided-during-onboarding>

See Authentication → M2M for how to build the assertion, and for a common aud/trailing-slash mistake that produces a confusing invalid_grant error.

Step 2 — Resolve the actor you're acting on behalf of

Endpoints that need a broker identity reject a bare service-account token. Resolve the Quarzo identity for the subscriber or broker user you're acting on behalf of first:

GET /v1/authentication/subjects/{externalUserId}
Authorization: Bearer <service-account-access-token>

externalUserId is the identifier you assigned to that person when you registered them with Quarzo. See Authentication → M2M for the full step, including a RFC 8693 token-exchange step needed before calling business endpoints on behalf of that person.

Step 3 — Make your first request

For calls made as the service account itself (no end user involved), attach the access token from Step 1 as a bearer token:

GET /v1/accounts HTTP/1.1
Host: api.sandbox.quarzo-life.com
Authorization: Bearer <service-account-access-token>

A 200 response means you're set up correctly.

Security checklist

Before going to production, make sure you have:

• [ ] Stored your service-account JSON key outside your source repository (use a secrets manager or environment variable)
• [ ] Added the key file to your .gitignore
• [ ] Rotated to a production service account (sandbox credentials are rejected by the production endpoint)
• [ ] Normalized your IdP authority/aud values to have no trailing slash

Next steps

Authentication → Learn the M2M and user authentication flows in full, including token exchange and error codes.

Environments → Switch between the sandbox and production endpoints.

API reference → Browse all available endpoints.