Skip to content

API Authentication

Flow APIs use Bearer token authentication.

Getting a Token

Use the OIDC flow to obtain an access token:

  1. Redirect to Zitadel authorization endpoint
  2. User authenticates
  3. Exchange code for token
  4. Use token in API requests

Option 2: Personal Access Token

Request a personal access token from your administrator, or create one in the Admin Console under Account > CLI Tokens.

Using the Token

Include the token in the Authorization header:

curl -X GET "https://admin.iflow.intelliseq.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import httpx

headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
response = httpx.get(
    "https://admin.iflow.intelliseq.com/api/v1/projects",
    headers=headers
)

Project Context (X-Project-ID)

Most API endpoints are project-scoped and require an X-Project-ID header with the project's UUID. Without it you will receive a 400 Bad Request error.

Admin-service endpoints do NOT require this header — they operate at the organization or user level.

Getting your Project ID

Use the admin-service to list your projects and find the UUID:

curl -X GET "https://admin.iflow.intelliseq.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

[
  {
    "id": "924d3f2-725b-43be-99ba-9641e34fd486",
    "name": "My Project",
    "slug": "my-project",
    "org_id": "c42299b8-ac28-49e8-a3b9-6a808165dad2",
    "org_name": "My Organization",
    "bucket_name": "my-project-bucket"
  }
]

The id field is the value to use as X-Project-ID.

Making project-scoped requests

curl -X GET "https://miner.iflow.intelliseq.com/api/v1/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Project-ID: 924d3f2-725b-43be-99ba-9641e34fd486"

import httpx

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "X-Project-ID": "924d3f2-725b-43be-99ba-9641e34fd486",
}
response = httpx.get(
    "https://miner.iflow.intelliseq.com/api/v1/orders",
    headers=headers
)

HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + token);
conn.setRequestProperty("X-Project-ID", projectId);
conn.setRequestProperty("Accept", "application/json");

Which services require X-Project-ID?

Service X-Project-ID required?
Admin (admin.iflow.intelliseq.com) No
Miner (miner.iflow.intelliseq.com) Yes
Compute (compute.iflow.intelliseq.com) Yes
Files (files.iflow.intelliseq.com) Yes

Token Expiration

Access tokens expire after 1 hour. Use refresh tokens to obtain new access tokens without re-authenticating.

Error Responses

Status Meaning Common cause
400 Bad request Missing X-Project-ID header on a project-scoped endpoint
401 Not authenticated Missing, invalid, or expired token
403 Forbidden Token valid but insufficient permissions for this resource

Token types

iFlow recognises three token types in practice. Pick the one that matches your use case.

Token type Issued to Typical use Lifetime
OIDC access token An interactive user via Zitadel Browser sessions, admin UI 1 hour (+ refresh)
Personal Access Token (PAT) A specific user, long-lived CLI, scripts, CI Configurable per token
Service user JWT A non-human automation account Service-to-service automation Short-lived; refreshed from a signed key

The Authorization: Bearer <token> header is the same for all three types; the backend distinguishes them automatically.

Cross-service authentication

All iFlow services share authentication through Redis-backed sessions. The admin service is the only service that handles the OIDC login redirect with Zitadel; once a session cookie is set, every other service (miner, compute, file, report, vcf, audit) reads the session from Redis via the flow_session cookie.

For programmatic access, the Bearer token flow above bypasses the cookie path: the token is validated and resolved to an effective role set on every request.

Effective roles

Authorization decisions use the effective_roles field on the session — computed from the RBAC store at login and cached. See the RBAC Matrix for the role hierarchy.

Creating a Personal Access Token

From the admin console:

  1. Log in as the user you want the PAT to represent.
  2. Go to Account → CLI Tokens.
  3. Click New token, choose a name and expiration, and copy the token value shown once.

The PAT is scoped to the user's effective roles at the time it is used — revoking the user's roles automatically restricts the PAT.

Which service owns the token?

Zitadel is the identity provider for all iFlow environments (https://zitadel.iflow.intelliseq.com). It issues OIDC tokens and maintains user identities. PATs and service-user keys are managed by the admin service.