Skip to content

Sign-In Providers API

The sign-in provider endpoints power the Providers, Link approvals, Invitations, and Log tabs in the UI. All management endpoints require the Admin user role.

Tip

For complete API documentation, including request and response schemas, visit the API docs on your Qualytics deployment.

All endpoints are served from your Qualytics deployment (e.g., https://your-instance.qualytics.io). The paths below include the /api prefix. Authenticate management requests with a Bearer token belonging to an Admin account. The public sign-in and recovery endpoints at the end of this page do not require that token.

List endpoints return paginated results and accept page and size. Use the returned items, page, size, and total to retrieve additional pages.

Invitations

The invitation endpoints require an enabled Email & Password sign-in provider. See Invite a User for the flow.

Invite User

Endpoint: POST /api/auth/db/invite

Permission: Admin user role

Request Body:

{
  "email": "new.user@example.com",
  "role": "Member"
}

role is optional and defaults to Member. The response includes the invitation status, its expiration time, and invite_link. A delivery failure returns a warning without canceling the invitation, so you can share the link securely with its intended recipient. Do not write invitation links to application logs.

The requested role applies to newly created accounts. An existing account retains its role, and adding password sign-in to it must satisfy the Email & Password provider's linking policy. Creating another invitation for the same email does not revoke earlier pending invitations.

List Invitations

Endpoint: GET /api/auth/db/invitations

Permission: Admin user role

Query Parameters:

Parameter Type Description
status string Filter by status (pending, accepted, revoked, expired). With no status filter, revoked invitations are excluded.
email string Filter by email (partial match)
sort_email string Sort by email (asc or desc)
sort_status string Sort by status (asc or desc)
sort_created string Sort by sent date (asc or desc)

Accepted invitations are normally removed after activation. Review the invite_accepted events from the Sign-In Log for acceptance history. Expired invitations can remain pending until an activation attempt updates their status.

Revoke Invitation

Endpoint: DELETE /api/auth/db/invitations/{id}

Permission: Admin user role

Only invitations with the pending status can be revoked. Revocation invalidates that link and hides the invitation from the default list. To retrieve revoked records, list invitations with status=revoked.

Providers

List Providers

Endpoint: GET /api/auth/providers

Permission: Admin user role

Returns a paginated list of provider configurations. Secrets (client secret, certificate) are never returned. Supports provider_type and enabled filters and sorting by name or created date.

Get Provider

Endpoint: GET /api/auth/providers/{id}

Permission: Admin user role

Create Provider

Endpoint: POST /api/auth/providers

Permission: Admin user role

The body depends on the provider type (oidc, saml2, or password). A minimal OIDC example:

{
  "display_name": "Corporate SSO",
  "provider_type": "oidc",
  "enabled": false,
  "oidc_discovery_url": "https://idp.example.com/.well-known/openid-configuration",
  "oidc_client_id": "your-client-id",
  "oidc_client_secret": "your-client-secret"
}

Only one password provider can exist; creating a second one fails.

Keep a new SSO provider disabled while configuring it. Register the provider's callback details at your identity provider, run diagnostics, then enable it and complete a real sign-in before retiring another provider.

Update Provider

Endpoint: PUT /api/auth/providers/{id}

Permission: Admin user role

The body must include expected_configuration_version (returned by the read endpoints). If another administrator changed the provider in the meantime, the update fails with a conflict and you reload the provider first. Disabling a provider is an update with "enabled": false and ends sessions issued through it. You cannot disable the last enabled customer provider or the provider used by your current sign-in session.

Delete Provider

Endpoint: DELETE /api/auth/providers/{id}

Permission: Admin user role

Fails with a conflict while users are still associated with the provider, or when it is the last enabled customer sign-in provider.

Preview Metadata (Discovery)

Endpoint: POST /api/auth/providers/oidc/discover and POST /api/auth/providers/saml2/discover

Permission: Admin user role

Fetches the identity provider's discovery document or SAML metadata and returns the values that would be filled in, without saving anything.

Run Diagnostics

Endpoint: POST /api/auth/providers/{id}/diagnose (saved provider) and POST /api/auth/providers/diagnose (unsaved configuration)

Permission: Admin user role

Returns the list of checks with a pass, fail, warning, or skipped status each, plus an overall status. Not supported for the password provider type.

Google Workspace Authorization

Endpoint: POST /api/auth/providers/{id}/google-workspace/authorize, POST /api/auth/providers/{id}/google-workspace/verify, and DELETE /api/auth/providers/{id}/google-workspace/authorization

Permission: Admin user role

Starts, verifies, and removes the Google Workspace administrator authorization used to fetch group membership. The authorization link returned by the authorize endpoint is single-use and short-lived.

Endpoint: GET /api/auth/links/pending

Permission: Admin user role

Each pending request carries the requester's account, the provider, the subject identifier reported by the identity provider, the trust evidence (verified email, allowed domain, signed assertion), and the request time.

Endpoint: POST /api/auth/links/{id}/approve and POST /api/auth/links/{id}/reject

Permission: Admin user role

Approval works on a pending request and also on one that was previously rejected, so a rejection can be reversed. Rejection works only on a pending request.

Approval preserves the existing account's role and Team memberships. It does not bypass provider restrictions or reactivate a deactivated account. No notification is sent; tell the user to sign in again after approval.

Endpoint: DELETE /api/auth/links/{id}

Permission: Admin user role

Removes the link between an account and a provider, whatever its state. Use it to clear a mistaken rejection or a pre-created link: the person's next sign-in through that provider starts the linking flow again, following the provider's current linking settings.

Bulk Approve

Endpoint: POST /api/auth/links/bulk-approve

Permission: Admin user role

Approves pending links by ID list or for an entire provider.

Endpoint: POST /api/auth/providers/{id}/backfill-links

Permission: Admin user role

Pre-creates approved links between existing users and an OIDC or SAML provider, so existing users do not land in the approval queue when they first sign in through that provider. Runs as a dry run by default. DELETE /api/auth/providers/{id}/backfill-links removes unused pre-created links.

Sign-In Log

List Auth Events

Endpoint: GET /api/auth/audit

Permission: Admin user role

Query Parameters:

Parameter Type Description
user_id int Only events for this user.
event_type string One or more event types, comma-separated.
provider_type string Only events for this provider type (oidc, saml2, password).
filters string (JSON) Narrows the list by one or more filters, written as a JSON object. See Filtering Lists.
from / to datetime Time range.
sort_created string Sort by timestamp (asc or desc).
sort_event_type string Sort by event type (asc or desc).
sort_outcome string Sort by outcome (asc or desc).

Use ISO 8601 timestamps for from and to; both bounds are inclusive. Each event includes the associated user when known, provider, IP address, outcome, and a details object; sensitive values are redacted. The outcome may be a specific reason rather than only success or failure.

For example, filter event_type=invite_sent,invite_accepted to review invitation activity. invite_sent records the administrator who created the invitation, with the invited email in details; it is not an email-delivery receipt. Link decisions use linking_approved and linking_rejected.

Filtering Lists

GET /api/auth/audit accepts a filters parameter: a JSON object with one entry per filter, saying how that filter's values should match.

curl -G "https://your-instance.qualytics.io/api/auth/audit" \
  --data-urlencode 'filters={"event_type":{"not_in":["invite_sent"]}}' \
  -H "Authorization: Bearer YOUR_TOKEN"

This returns every event except sent invitations.

Key Returns
in The items that match at least one of the values.
not_in The items that match none of the values.
all_of The items that match every value, on filters an item can have several of, such as tags.
empty The items with no value (true) or at least one (false), on filters an item can lack.
  • Different filters combine with AND, and so do keys on the same filter.
  • empty can't be combined with other keys on the same filter.
  • A filter sent both as its own parameter and inside filters returns a 422. Put all of that filter's conditions in filters.
  • in, not_in and all_of each take between 1 and 20 values.
  • A filter or key the endpoint doesn't accept returns a 422 that names it. The API docs list what each endpoint accepts.

Sign-In (Public Endpoints)

These endpoints serve sign-in, initial enrollment, invitations, and password recovery without an existing authenticated session. Password operations require Email & Password sign-in to be enabled. Invitation acceptance and password reset require the token from the corresponding email or invitation link.

Endpoint Purpose
GET /api/auth/providers/available The enabled customer sign-in providers shown on the sign-in page.
GET /api/auth/saml2/metadata?provider_id={id} The SAML service provider metadata document for your identity provider to import.
GET /api/auth/db/password-policy The password rules displayed on the password screens.
GET /api/auth/db/bootstrap/status Whether first-administrator enrollment is still available.
POST /api/auth/db/bootstrap Create the first Admin on an empty deployment. Accepts email, password, and optional name.
POST /api/auth/db/login Sign in using email and password.
POST /api/auth/db/invite/accept Accept an invitation using its token and the chosen password.
POST /api/auth/db/password/reset-request Request a reset email using email. The response does not disclose whether an account exists.
POST /api/auth/db/password/reset Complete password recovery using token and the new password.