JumpStart AMS Integration
Cosmos OAuth, SDK, backend API, and frontend API-base contracts for JumpStart AMS
Updated 2026-11-03
Verified 2026-11-03
AMS integrates with Cosmos from the backend. The frontend calls AMS APIs; the backend decides when to call Cosmos as the signed-in user or as a service client.
Cosmos OAuth
| Setting | Purpose |
|---|---|
AMS_PUBLIC_API_BASE_URL | Public backend URL; callback is ${AMS_PUBLIC_API_BASE_URL}/api/v1/auth/callback |
AMS_FRONTEND_URL | Safe post-login/logout redirect target |
COSMOS_USER_SERVICE_URL | Authorization, token exchange, JWKS, and identity source |
COSMOS_CLIENT_ID, COSMOS_CLIENT_SECRET | Cosmos OAuth client for browser login |
COSMOS_OAUTH_SCOPE | Default scope is read agent:execute tools:call |
COSMOS_ORG_ID | Org context stored into AMS sessions and service clients |
Auth status is exposed through /api/v1/auth/config, /api/v1/auth/me, /api/v1/auth/logout, and /api/v1/auth/switch-project. Login and callback routes are browser redirects, not JSON APIs.
SDK Modes
| Mode | Builder | Used for |
|---|---|---|
| User-scoped | build_user_cosmos_adapter(session) | User-visible AI/chat/resource actions that should use the signed-in user's Cosmos token |
| Client credentials | CosmosClient.from_client_credentials() | Audience-bound backend service calls using COSMOS_SERVICE_CLIENT_ID and COSMOS_SERVICE_CLIENT_SECRET |
The backend wraps cosmos-sdk-python behind CosmosAMSAdapter. It supports ADK V2 messages, Configurator/collection lookups, Storage uploads/downloads, RAGflow searches, BYOT/model reads, and role/user queries needed by AMS workflows.
Service-scoped clients come from auth/service_tokens.py, which uses the Python SDK's CosmosClient.from_client_credentials() with COSMOS_SERVICE_CLIENT_ID and COSMOS_SERVICE_CLIENT_SECRET (COSMOS_SERVICE_TOKEN_SCOPE defaults to read). A static COSMOS_SERVICE_ACCESS_TOKEN is accepted instead when no client credentials are configured. See Python SDK Service Auth and Authentication.
Project Roles And Permissions
Cosmos authenticates the user; AMS authorizes project work from its own project memberships.
| Aspect | Behavior |
|---|---|
| Session | The jumpstart_ams_session cookie maps to a Redis-backed AMS session holding the Cosmos tokens; access tokens are validated against the User Service JWKS |
| Project role source | The active project's AmsProjectMembership row in the AMS database. The project and the membership must both be active |
| Role permissions | support_admin: admin.*, tickets.*, automation.*; support_manager: tickets.*, reports.*, routing.*, sla.*, kb.read; support_team: tickets.read, tickets.update, kb.read; end_user: tickets.create, tickets.own.read, kb.read. Unknown roles are treated as end_user |
| No active project | Roles and permissions fall back to the session/token claims |
| Permission checks | require_permission matches wildcard patterns. Superusers and the admin roles admin, support_admin, platform_admin, and ams_support_admin pass every check |
| Superuser | A Cosmos superuser is an AMS superuser only when their project role is support_admin or they have no project role; cosmos_is_superuser reports the raw Cosmos flag |
| Project list and switching | Available projects come from the user's AMS memberships; /api/v1/auth/switch-project rejects projects the user is not a member of |
/api/v1/auth/me | Returns roles, permissions, and available_projects, each with capabilities and authority_source (cosmos_canonical when the project is linked to a Cosmos project, otherwise ams_snapshot), plus Ticket Intelligence flags |
| Ticket Intelligence workspace | Open to Cosmos super admins and to users with a ti_workspace_grants row for the active project |
| Session lifetime | Inactivity timeout from the general_settings session_timeout setting (default 60 minutes); concurrent requests share one refresh so single-use refresh tokens are not replayed |
In the user directory, only support managers and support team members carry teams, shifts, and skills, and only support managers can lead a team. The jumpstart-ams-backfill-project-rbac command backfills project memberships.
ADK Usage
AMS sends ADK work through the Python SDK. The adapter accepts agent/model options, skills, collection IDs, image references, user ID, session ID, and channel metadata. COSMOS_ADK_WS_OPEN_TIMEOUT_SECONDS (default 45) sets the ADK WebSocket open timeout.
Ticket AI and virtual-agent features should call backend AMS APIs; they should not connect the browser directly to ADK.
Frontend API Contract
The frontend uses NEXT_PUBLIC_API_BASE_URL, defaulting to http://localhost:8300, and appends /api/v1. Requests include browser credentials so the backend receives jumpstart_ams_session.
NEXT_PUBLIC_API_BASE_URL=https://<ams-backend-host>
Only NEXT_PUBLIC_* values are safe for browser exposure. Rebuild the frontend image after changing them because Next.js embeds public values at build time.
Backend-Owned APIs
All AMS business APIs are backend-owned. The major API groups are tickets, attachments, knowledge, chat, routing, SLA, teams, catalog, dashboards, integrations, imports, projects, super admin, AI operations, automation, audit/admin settings, and health.
The backend should be the only component that stores integration credentials, service tokens, OAuth client secrets, database URLs, Redis URLs, and Cosmos service credentials.