---
url: /topics/authentication.md
---
# Authentication

Quarzo supports four ways to authenticate. Select the way that matches the caller and the operation.

## Direct login

A person signs in to a Quarzo front end through Quarzo's identity provider, ZITADEL.
The front end uses Authorization Code with PKCE to obtain an access token for that person.

Use direct login when a person works in a Quarzo front end.
For example, a Broker Administrator signs in to `broker-front` to manage Service Accounts.
The `broker-admin` role permits administration operations. The `broker-advisor` role permits Broker business operations.

Guide: [Sign in to Quarzo](/guides/sign-in-to-quarzo#direct-login).

## Machine access

A Broker backend authenticates with a Service Key that belongs to a Broker Service Account.
The backend exchanges a signed JWT assertion for an access token through the JWT Bearer Grant.

Use machine access for operations that the backend performs as the Broker Service Account.
For example, a scheduled process reads payer information for a Subscriber of its Broker.
The machine token calls business endpoints directly with the `broker-advisor` role.
The token identifies the machine. It does not identify a human subject.

Guide: [Call Quarzo from a Broker backend](/guides/call-quarzo-from-a-broker-backend).

## Delegation

The Broker authenticates its users in its own system, with its own authentication method.
The Broker backend uses a delegated token to call Quarzo for an authenticated Subscriber or Broker Advisor.
The token identifies both the human subject and the Broker Service Account that acts for that subject.

Use delegation when Quarzo must identify the person who performs an operation through a Broker system.
For example, a Subscriber requests an insurance operation in the Broker's application.
A Broker Administrator uses direct login for administration operations.

Guide: [Call Quarzo for a person](/guides/call-quarzo-from-a-broker-backend#5-call-quarzo-for-a-person).

## Federation

Federation lets an invited Broker-side User sign in to a Quarzo front end with the Broker's identity provider.
ZITADEL issues the Quarzo access token after the external login.
The user's Quarzo identity and roles stay the same.

Use federation when a Broker requires its employees to use its identity provider for access to Quarzo front ends.
For example, a Broker Advisor signs in to `broker-front` with the Broker's company account.
Quarzo operations must configure the provider first. The user must already have a Quarzo invitation.

Guide: [Sign in with a Broker identity provider](/guides/sign-in-to-quarzo#federation).

## Authentication and permission errors

| Status | Meaning | Action |
| --- | --- | --- |
| `401 Unauthorized` | Quarzo cannot authenticate the caller. The token can be missing, expired, or inactive. A revoked Service Key also prevents access. | Check the key, token, audience scope, and environment. Obtain a new token with an active key. |
| `403 Forbidden` | Quarzo identifies the caller, but the caller lacks a required role or permission. | Check the endpoint's required permissions. Ask the Broker Administrator to check access. |

An access token does not grant access to every resource. Each endpoint also applies its resource access rules.