Authentication

Authentication in Jardine is straightforward at first glance, but it also carries scope and role implications that matter for real operations. If you understand those implications early, integration work becomes much safer and less surprising.

At a high level, the API uses token-based authentication with organization-aware behavior. The UI client handles most of this automatically, but teams building scripts or service integrations should model the same discipline explicitly.

Core Authentication Flow

The basic flow is familiar:

1. Register or log in.
2. Receive an access token.
3. Send Authorization: Bearer <token> with protected requests.

Common entry points include:

• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/me
• PATCH /api/auth/me

There are also password reset endpoints and Google OAuth start/exchange flows for teams using those paths.

From an operational perspective, auth/me is not just a profile call. It is often the first scope and membership sanity check for your active session.

Organization and Workspace Scope

Authentication alone is not enough to define behavior context. Requests also rely on scope.

In the frontend client, organization and workspace IDs can be attached as request headers (X-Organization-ID, X-Workspace-ID) when present in local state. This allows backend actions to operate in the intended context.

In current product behavior, support operations run in single-workspace mode, but workspace identifiers and APIs still exist and are used in access-management flows.

For custom integrations, the important lesson is to be explicit about scope assumptions. If your automation can operate across organizations, treat scope selection as a first-class control, not an afterthought.

Roles and Privileged Actions

Membership roles determine what authenticated users can do. Some actions are available broadly, while others require organization or workspace admin privileges.

In practice, this affects configuration endpoints and policy controls more than read-only operations. For example, certain routing profile edits and org-level setting changes are explicitly guarded in UI behavior.

When designing integrations for teams, map each automated action to the minimum required role and avoid over-privileged service behavior. Least privilege keeps mistakes recoverable.

Session Lifecycle Considerations

Authentication robustness is not just login success. It includes session refresh behavior, token expiry handling, logout hygiene, and account switching safety.

In frontend flows, expired or invalid tokens trigger cleanup and re-auth paths. For integration code, you should mirror that resilience: detect auth failures cleanly, refresh or re-auth when appropriate, and avoid infinite retry loops on invalid credentials.

If your integration handles multiple operators or organizations, add explicit guardrails so stale context from one session cannot leak into another.

OAuth Notes for Production Teams

Google OAuth and provider-specific connection flows (like channel integrations) are often confused with API auth itself. Keep them conceptually separate.

User authentication grants access to Jardine resources.

Provider OAuth (for channels/connectors) grants Jardine access to external systems.

Both are important, but they solve different trust problems. Mixing them mentally often leads to setup mistakes and delayed troubleshooting.

Common Authentication Pitfalls

The first pitfall is scope mismatch. Authenticated calls succeed, but changes appear in an unexpected context because organization/workspace assumptions are wrong.

The second pitfall is token reuse across environments. A token from one environment or org accidentally drives actions in another.

The third pitfall is role assumption. A call fails due to permissions, and teams chase payload issues instead of checking role constraints.

The fourth pitfall is poor logout or session cleanup in custom tooling, leading to stale state behavior.

A Practical Auth Readiness Checklist

Before running production automation, confirm:

• auth flow works for your chosen identity method,
• auth/me returns expected memberships,
• scope is explicitly selected and validated,
• privileged calls are mapped to appropriate roles,
• auth error handling is deterministic,
• token storage and lifecycle are secure and short-lived where possible.

This checklist prevents most early integration incidents.

Final Guidance

Treat authentication as the gateway to controlled operations, not just as a login step. The combination of token validity, role eligibility, and scope correctness is what makes API behavior predictable and safe.

When these are handled intentionally, the rest of your integration work gets much easier. When they are handled casually, every downstream system looks unstable even when it is not.

After this, continue with Key Endpoints for practical endpoint groups used most often in production workflows.