Authentication Methods in Xolo

Xolo supports five authentication types and a smart inheritance system that lets you define credentials once on a collection or folder and automatically apply them to every request inside it. Each request’s Auth tab lets you choose an explicit type, opt into inheritance, or explicitly disable auth — giving you fine-grained control without repetitive configuration.

Supported Auth Types

API Key auth injects a custom key-value pair into either the request Header or a Query parameter, depending on where the target API expects it.The ApiKeyAuthForm widget exposes three fields:

Field	Description
`key`	The header name or query parameter name (e.g. `X-API-Key`)
`value`	The secret key value
`in`	Destination: `header` or `query`

When in is set to header, Xolo adds a custom request header with the given name and value before the request is dispatched. When set to query, the key-value pair is appended to the request URL as a query parameter.

// Data shape stored for API Key auth
{
  "key": "X-API-Key",
  "value": "sk-abc123",
  "in": "header"   // or "query"
}

Bearer Token auth automatically prepends Bearer to the token value and injects it as the Authorization header on every request.The BearerAuthForm widget exposes a single field:

Field	Description
`token`	The raw bearer token string

Xolo constructs the final header as Authorization: Bearer <token> at request time, so you only need to store the token itself.

// Data shape stored for Bearer Token auth
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6..."
}

Basic Auth transmits a username and password encoded as a Base64 string in the Authorization header, following the standard Basic <base64(username:password)> scheme.The BasicAuthForm widget exposes two fields:

Field	Description
`username`	The account username
`password`	The account password

// Data shape stored for Basic Auth
{
  "username": "admin",
  "password": "s3cr3t"
}

Xolo supports three OAuth 2.0 grant types natively: Authorization Code with PKCE, Client Credentials, and Password Grant. The OAuth2AuthForm widget handles token acquisition and stores the resulting accessToken back into the auth data so it is injected as an Authorization: Bearer header on subsequent requests.Grant types available in the form dropdown:

Grant Type	Use Case
`client_credentials`	Machine-to-machine; no user interaction
`password`	User credentials passed directly
`authorization_code`	Full browser-based flow with PKCE

See the full OAuth 2.0 guide for step-by-step instructions, PKCE details, and token refresh behaviour.

OAuth 2.0 Guide

Configure grant types, PKCE flows, and token refresh.

Setting the auth type to none explicitly marks a request as unauthenticated. The AuthResolverService returns a ResolvedAuth with source: 'none' and no credentials — no auth header is added to the request.

Setting auth type to none on a request blocks inheritance — even if a parent folder or project has auth configured, the request will be sent without any credentials. This is useful for public endpoints that live inside an otherwise-authenticated collection.

When a request’s auth type is set to inherit (the default for new requests), Xolo automatically walks up the collection tree to find the nearest ancestor with an explicit, non-inherit auth configuration and applies it to the request.If no ancestor defines auth, the request is sent without credentials, just as if none were set directly.

Auth Inheritance

Xolo’s AuthResolverService.resolveAuth() implements a depth-first upward walk through the collection hierarchy to determine the effective auth for any request.

Future<ResolvedAuth> resolveAuth({
  String? requestAuthType,
  String? requestAuthData,
  int? collectionId,
}) async { ... }

The resolution algorithm follows these steps in order:

Direct auth — if requestAuthType is not null, not 'inherit', and not 'none', the request’s own auth is used and source is set to 'request'.
Explicit none — if requestAuthType == 'none', resolution stops immediately and returns source: 'none' with no credentials.
Inheritance walk — if requestAuthType == 'inherit' (or is null), resolveAuth calls _repo.getCollectionPath(collectionId) which returns the full ancestor chain ordered [Root, …, DirectParent]. The list is reversed so the closest ancestor is checked first.
For each ancestor collection, if its authType is a non-empty, non-'inherit', non-'none' value, that auth is resolved and returned. The source field distinguishes whether the winning ancestor is a folder (parentId != null) or the root project (parentId == null).
If an ancestor has authType == 'none', inheritance stops and source: 'none' is returned, preventing further upward lookup.
If no ancestor yields auth, source: 'none' is returned.

The source field on ResolvedAuth tells you exactly where the active credentials came from:

`source`	Meaning
`'request'`	Auth is defined directly on the request
`'folder'`	Auth is inherited from an intermediate folder
`'project'`	Auth is inherited from the root project collection
`'none'`	No auth is active

Resolved Auth Preview

The Auth tab in the request composer includes an AuthResolvedPreview widget that shows you the final resolved auth in real time — before you send the request. It calls AuthResolverService.resolveAuth() asynchronously and displays:

The resolved auth type (e.g. BEARER, BASIC, API_KEY)
The source — whether credentials come from the request itself, an inherited folder, or the root project
A clear message when no auth is active

This prevents surprises: you can confirm at a glance which credentials will be injected into the next request, even when inheritance is involved.

Secure Storage

Xolo never stores authentication credentials in plaintext SQLite. All auth secrets are written through AuthSecretService, which delegates to SecurityService — a thin wrapper around flutter_secure_storage. When you save auth data, AuthSecretService.storeAuthData():

Writes the serialised JSON to flutter_secure_storage under a namespaced key prefixed with auth_secret:.
Returns an opaque reference string (prefixed secure_auth_ref:) that is stored in the database in place of the real credentials.

At resolution time, AuthSecretService.resolveAuthData() detects the reference prefix and fetches the actual secret from secure storage — keeping credentials out of the SQLite database entirely.

// Writing credentials
final ref = await authSecretService.storeAuthData(jsonEncode({
  "token": "eyJhbGc..."
}));
// ref == "secure_auth_ref:1718000000000-abc123def456"

// Reading credentials (called internally by AuthResolverService)
final raw = await authSecretService.resolveAuthData(ref);
// raw == '{"token":"eyJhbGc..."}'

flutter_secure_storage uses the Android Keystore on Android and the iOS Keychain on iOS, so credentials are protected by the device’s hardware security module where available.

OAuth 2.0

Configure Authorization Code + PKCE, Client Credentials, and Password grant flows.

Biometric Security

Lock the app with Face ID or fingerprint and protect stored credentials.

Get Started

Core Features

Authentication

Scripting & Automation

Import & Sync

Authentication Methods in Xolo

Supported Auth Types

OAuth 2.0 Guide

Auth Inheritance

Resolved Auth Preview

Secure Storage

OAuth 2.0

Biometric Security

Build docs developers (and LLMs) love

Get Started

Core Features

Authentication

Scripting & Automation

Import & Sync

Documentation Index

​Supported Auth Types

OAuth 2.0 Guide

​Auth Inheritance

​Resolved Auth Preview

​Secure Storage

OAuth 2.0

Biometric Security

Build docs developers (and LLMs) love

Supported Auth Types

Auth Inheritance

Resolved Auth Preview

Secure Storage