Use the auth lane to mint tokens, move casework through REST and GraphQL, and keep realtime plus audit behavior visible from one command-center reference.
Reference posture
Start in the auth lane, move requests through the operational API, and keep realtime and audit controls visible from the same reference surface.
Auth endpoints
80+
REST endpoints
130+
GraphQL operations
180+
Realtime subscriptions
WS
API operating model
The platform exposes separate identity and operational API lanes so integrators can scope token issuance, investigative data access, and realtime subscriptions without collapsing them into one generic surface.
auth.knogin.com
Handles all authentication, user management, MFA, SSO, API keys, roles, permissions, and session management. This is where you obtain tokens for accessing the API Service.
Surface
80+ Endpoints
Identity lane
OAuth2/OIDC
Operator assurance
TOTP/Passkey/Voice MFA
api.knogin.com
The core intelligence platform API providing REST endpoints and GraphQL for investigations, cases, profiles, evidence, alerts, monitors, AI services, and real-time communication.
REST lane
130+ REST Endpoints
Graph surface
180+ GraphQL Operations
Realtime lane
WebSocket
Base URLs
Use the production lane for live workloads and the staging lane for validation, connector certification, and client rollout rehearsals.
Auth Service (Production)
https://auth.knogin.comAPI Service (Production)
https://api.knogin.comAuth Service (Staging)
https://auth-staging.knogin.comAPI Service (Staging)
https://api-staging.knogin.comAuthentication
All authenticated API requests require a valid argus_auth_token. Tokens are obtained through the Auth Service and must be included in all subsequent requests to both services. API keys can be generated in the Auth Service dashboard under your user profile for programmatic access.
curl -X POST https://auth.knogin.com/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"api_key":"your_api_key","platform":"publicSafety"}'
# Response
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600
}Product context
The same investigation state exposed to analysts is what the API and GraphQL layers need to describe accurately.
Analysis context
Graph and realtime endpoints should map directly to the linked entity and workflow state teams review in the product.
Request flow
The fastest way to make an API page feel synthetic is to dump endpoints without showing how the lanes fit together. This flow keeps the operational order clear.
Issue short-lived access tokens, enforce MFA or passkey policy, and scope platform access before a client is allowed near investigative data.
Move ingestion, enrichment, graph, evidence, and reporting calls through the API lane with the same token and RBAC posture.
Use GraphQL subscriptions or event streams when teams need live alerts, workflow updates, and collaboration signals without polling loops.
Keep response envelopes, rate limits, and audit proofs visible so integration teams know what is reviewable in production and court-facing workflows.
Common headers
Browser clients normally hold HTTP-only cookies. Server clients carry bearer tokens. Both end up under the same audit and rate-limit controls.
Authorization: Bearer <argus_auth_token>
Cookie: platform_access_token=<jwt>; knogin_refresh_token=<jwt>AUTH SERVICE
The Auth Service (auth.knogin.com) handles all authentication, authorization, user management, MFA, SSO, API keys, roles, permissions, feature flags, and multi-tenant management. It contains 80+ endpoints organized by functionality.
Core authentication endpoints for obtaining, refreshing, and managing access tokens and sessions.
/v1/tokenOAuth2-compatible login endpoint that accepts form-encoded email and password. Issues platform-specific access tokens and sets HTTP-only cookies (platform_access_token, knogin_refresh_token) for browser sessions. If MFA is enabled, returns a challenge cookie instead requiring verification via /v1/mfa/verify-login. Supports redirect_uri for post-login navigation.
/v1/auth/tokenAuthenticate using an API key to receive a platform-specific JWT token. Ideal for service-to-service authentication, CI/CD pipelines, and programmatic access. API keys can be generated in the Auth Service dashboard under your user profile. Request body requires api_key and platform fields.
/v1/auth/refreshRefresh expired access tokens using the knogin_refresh_token cookie. Returns new access token cookies without requiring re-authentication. Supports optional platform path parameter for platform-specific token refresh. Essential for maintaining long-lived sessions in browser applications.
/v1/auth/logoutTerminates the current user session by invalidating all tokens and deleting authentication cookies. Removes the session from the server-side session store. Supports optional platform path parameter. Returns 204 No Content on success.
/v1/auth/revoke-user-sessions/{user_id}Forcefully terminates all active sessions for a specific user across all devices and platforms. Used for security incidents or when a user's access needs to be immediately revoked. Returns count of sessions revoked. Requires admin or superuser role.
Endpoints for users to manage their own profiles, view their information, and update their settings.
/v1/users/meReturns the complete profile of the currently authenticated user including email, display name, organization, roles, permissions, MFA status, created date, and last login timestamp. Used by frontend applications to populate user dashboards and check permissions.
/v1/users/meAllows users to update their own profile information including display name, phone number, and password. If password is changed, all other sessions are automatically terminated for security. Requires current password verification for sensitive changes.
/v1/auth/meReturns current user profile along with evaluated feature flags for the user's tenant and any user-specific overrides. Used by frontend applications to determine which features to display based on the user's subscription tier and enabled experiments.
/v1/users/createPublic endpoint for new users to create an account. Accepts email and password, creates the user in the system, and sends a verification email. Rate limited to 2 requests per hour per IP to prevent abuse. Returns the created user object.
Comprehensive MFA support including TOTP (authenticator apps), WebAuthn passkeys, and voice verification. Users can enable multiple methods for layered security.
/v1/portal/mfa/totp/enableGenerates a new TOTP secret and returns it along with a QR code image (base64 encoded) for scanning with authenticator apps like Google Authenticator, Authy, or 1Password. The secret is stored in pending state until verified.
/v1/portal/mfa/totp/verify-and-activateVerifies a TOTP code from the user's authenticator app and activates TOTP MFA for their account. Requires the 6-digit code from the authenticator app. Once activated, TOTP will be required for all future logins.
/v1/mfa/verify-loginValidates the MFA code (TOTP) during the login challenge flow. Called after initial login when MFA is required. Requires the TF_AUTH challenge cookie and the 6-digit TOTP code. On success, issues full access tokens.
/v1/portal/mfa/passkey/generate-registrationGenerates WebAuthn registration options for creating a new passkey credential. Returns challenge, relying party info, and supported algorithms. Used by the browser's WebAuthn API (navigator.credentials.create) to create a new passkey.
/v1/portal/mfa/passkey/verify-registrationVerifies the WebAuthn attestation response from the browser and saves the new passkey credential. Stores the public key, credential ID, and metadata. Users can register multiple passkeys for different devices.
/v1/portal/mfa/voice/enrollEnrolls a voice sample for voice-based MFA. Accepts base64-encoded audio data of the user speaking a passphrase. The voice print is processed and stored for future verification. Requires multiple samples for accurate enrollment.
OAuth2/OIDC-based single sign-on integration with enterprise identity providers including Google Workspace and Microsoft Entra ID (Azure AD).
/v1/portal/sso/available-providersReturns a list of SSO providers configured for the current tenant. Response includes provider names and count. Used by login UI to display available SSO login buttons (e.g., 'Sign in with Google', 'Sign in with Microsoft').
/v1/portal/login/{provider}Initiates the OAuth2/OIDC authorization flow with the specified identity provider. Redirects the user to the provider's login page (Google, Microsoft). Accepts redirect_uri for post-login navigation.
/v1/portal/auth/{provider}OAuth2/OIDC callback endpoint that handles the authorization code returned by the identity provider. Exchanges code for tokens, creates or updates user account, and establishes session with cookies.
Create and manage API keys for programmatic access. API keys can be scoped to specific platforms and have configurable expiration.
/v1/portal/users/me/keysCreates a new API key for programmatic access. The full key is only returned once at creation time - store it securely. Supports platform scoping and optional expiration date. Returns key prefix for identification.
/v1/portal/users/me/keysReturns all API keys for the current user. Shows key prefix, created date, last used date, and associated platforms. Does not return the full key value for security.
/v1/portal/users/me/keys/{key_id}Permanently revokes an API key, immediately invalidating all tokens issued using this key. Any applications using this key will immediately lose access. Cannot be undone.
Administrative endpoints for managing users, roles, and permissions. Access varies based on role hierarchy.
/v1/portal/admin/usersReturns all users based on the caller's role. Managers see users in their organization only. Superusers see all users across all organizations. Supports pagination and filtering by role, status, and organization.
/v1/portal/admin/usersCreates a new user with specified email, password, roles, and organization assignment. Optionally sends welcome email. Can assign initial platform access and security clearance level. Superuser only.
/v1/portal/admin/users/{user_id}Updates user details including roles, permissions, platform access, and security clearance. Can activate/deactivate users. Role changes take effect on next token refresh. Superuser only for cross-org changes.
/v1/users/{user_id}/permissionsUpdates a user's granular permissions independent of their role-based permissions. Allows fine-tuning access control. Admin or superuser only. Returns updated permission set.
Define custom roles and granular permissions for fine-grained access control within organizations.
/v1/rolesReturns all roles available in the system including built-in roles (admin, manager, analyst, viewer) and custom roles defined for the organization. Includes permissions associated with each role.
/v1/rolesCreates a new custom role with specified permissions. Custom roles extend the built-in role hierarchy. Superuser only. Role names must be unique within the organization.
/v1/roles/{role_id}Updates a custom role's name, description, or permissions. Changes affect all users with this role on their next token refresh. Cannot modify built-in roles. Superuser only.
/v1/roles/{role_id}Deletes a custom role. Users with this role will lose associated permissions. Cannot delete roles currently assigned to users. Cannot delete built-in roles. Superuser only.
Control feature availability at tenant and user level for gradual rollouts and A/B testing.
/v1/feature-flags/tenantReturns all feature flags and their values for the current tenant. These are the base flags that apply to all users in the organization unless overridden at the user level.
/v1/feature-flags/tenantUpdates feature flags for the tenant. Changes apply to all users in the organization unless they have user-level overrides. Used to enable/disable features for the entire organization.
/v1/feature-flags/user/{user_id}Returns user-specific feature flag overrides. These override tenant-level flags for individual users. Used for beta testing with specific users or providing premium features to select accounts.
/v1/feature-flags/user/{user_id}Sets user-specific feature flag overrides. Overrides can only be a subset of organization flags - cannot enable flags not available to the tenant. Returns updated user flags.
Manage the multi-tenant hierarchy including Systems Integrators (SI) who resell and manage Public Safety deployments for their customers.
/v1/systems-integratorsCreates a new Systems Integrator organization that can manage multiple customer tenants. Vectis Consilium admin only. SI receives their own admin portal and can create/manage customer deployments.
/v1/systems-integrators/{si_id}/customersReturns all customer tenants managed by a Systems Integrator. SI admins can only view their own customers. Includes tenant status, user count, and feature enablement.
/v1/systems-integrators/{si_id}/customersCreates a new customer tenant under a Systems Integrator. The SI becomes the managing entity for billing and support. Configures initial features based on SI's subscription tier.
/v1/tenants/{tenant_id}Updates tenant configuration including name, features, quotas, and metadata. Used to enable/disable features or adjust resource limits for a customer.
Administrative configuration and utility endpoints.
/v1/portal/admin/configReturns configuration data for the admin UI including available roles, permissions catalog, country list, supported platforms, and feature availability. Used to populate admin dashboard dropdowns and forms.
/v1/portal/data/countriesReturns a list of all countries with their regions/states for address forms. Includes ISO codes, names, and subdivisions. Public endpoint used by registration and profile forms.
/healthSimple health check endpoint that returns service status. Used by load balancers and monitoring systems. Returns status: healthy, service: auth_service.
/audit/logsReturns security audit logs for the authentication service. Includes login attempts, permission changes, and administrative actions. Administrator with audit permission required.
API SERVICE
The API Service (api.knogin.com) is the core intelligence platform providing 130+ REST endpoints for investigations, cases, profiles, evidence, alerts, AI services, real-time communication, and more. All endpoints require authentication unless marked as public.
System health monitoring and capability discovery endpoints for integration and monitoring.
/api/v1/healthReturns detailed health status of all system components including Neo4j graph database, PostgreSQL relational database, Redis cache, AI services (OpenAI, Anthropic, Google AI), and external integrations. Response includes latency metrics and connection status for each component. Used for operations monitoring and incident response.
/api/v1/health/simpleLightweight health check returning minimal response for load balancers and orchestration systems (Kubernetes, Cloud Run). Returns 200 OK if service is running. Does not check downstream dependencies for faster response time.
/api/v1/health/connectivityChecks connectivity to all external services including AI providers, OSINT data sources, storage systems, and notification services. Returns detailed status for each integration point.
/api/v1/capabilitiesReturns comprehensive system capabilities for frontend configuration including supported domains, available OSINT providers, accepted file formats, API endpoints, enabled features, rate limits, and maximum file sizes. Essential for dynamic UI configuration.
AI-powered document processing for extracting entities, relationships, and intelligence from text, images, audio, and video files.
/api/v1/intelligence/process-textUpload and process text, PDF, or DOCX files for investigation. Uses AI to extract entities (people, organizations, locations), relationships, events, and key intelligence from documents. Supports files up to 50MB. Results are stored and linked to the investigation.
/api/v1/process-image-fileUpload and process images for AI-powered visual analysis. Performs OCR text extraction, object detection, face detection, location identification, and scene classification. Supports JPEG, PNG, GIF, and WebP formats.
/api/v1/process-audio-fileUpload and process audio files for transcription and speaker identification. Uses advanced speech-to-text and speaker diarization. Supports MP3, WAV, OGG, and M4A formats up to 100MB.
/api/v1/process-video-fileUpload and process video files for comprehensive analysis. Extracts audio transcription, detects faces across frames, identifies scenes and objects, and generates visual timeline. Supports MP4, MOV, AVI, WebM up to 500MB.
Create, update, and enrich entity profiles with data from OSINT providers. Supports individual and batch operations.
/api/v1/profilesCreates a new entity profile (person, organization, vehicle, etc.). Accepts initial data and automatically validates/normalizes fields. Triggers background enrichment if auto_enrich is enabled.
/api/v1/profiles/{profile_id}Returns complete profile data including all attributes, linked entities, timeline, and enrichment data. Supports field selection for performance optimization.
/api/v1/profiles/{profile_id}/enrichEnriches a profile with data from OSINT providers. Optionally specify which providers to use (social, criminal, financial, etc.). Returns aggregated data including social media presence, public records, and open-source intelligence.
/api/v1/batch/enrichEnriches multiple profiles in a single request. Maximum 10 profiles per request to manage provider rate limits. Returns individual success/failure status for each profile.
Manage investigations, cases, tasks, and the complete investigation lifecycle.
/api/v1/investigationsCreates a new investigation workspace with title, description, and classification level. Automatically assigns the creator as lead investigator. Returns investigation ID for subsequent operations.
/api/v1/investigations/{investigation_id}Returns complete investigation details including metadata, team members, cases, profiles, files, and activity timeline. Supports field selection for large investigations.
/api/v1/investigationsReturns investigations accessible to the current user. Supports filtering by status, date, team member, and search query. Paginated with sorting options.
/api/v1/investigations/{investigation_id}/filesAssociates uploaded files with an investigation. Files are automatically queued for AI processing based on type. Triggers indexing for search.
Configure monitoring rules and manage alerts triggered by real-time data streams.
/api/v1/alertsProgrammatically creates an alert. Typically alerts are created by monitors, but manual creation is supported for integrations. Requires title, severity, and at least one entity reference.
/api/v1/alerts/{alert_id}/decideRecords a decision on an alert: escalate, investigate, dismiss, or false positive. Decision includes rationale and optional entity disposition. Closed alerts may trigger follow-up workflows.
/api/v1/monitorsCreates a monitoring rule that triggers alerts based on data stream patterns. Supports complex conditions with entity matching, geographic bounds, temporal patterns, and threshold triggers.
/api/v1/ai/generate-monitor-specUses AI to convert natural language descriptions into structured monitor specifications. Includes safety analysis, parameter extraction, and estimated alert volume. Helps non-technical users create complex monitors.
Direct access to AI capabilities including text analysis, entity extraction, relationship mapping, and natural language processing.
/api/v1/ai/analyze-textPerforms comprehensive AI analysis on text content. Extracts entities, relationships, events, sentiment, and key themes. Supports multiple languages with automatic detection.
/api/v1/ai/generate-graphCreates a knowledge graph from unstructured text. Identifies entities, infers relationships, and generates structured graph data suitable for visualization or Neo4j import.
/api/v1/ai/summarizeGenerates concise summaries of long-form content. Supports multiple summary lengths and styles (executive, technical, bullet points). Preserves key entities and facts.
/api/v1/ai/extract-entitiesExtracts and classifies named entities from text. Returns entity spans, types, confidence scores, and resolved identifiers where available. Supports custom entity types.
Upload, download, and manage files with full RBAC enforcement and audit logging.
/api/v1/filesUploads a file to secure storage. Automatically detects file type and queues for appropriate processing. Returns file ID and processing status. Supports chunked uploads for large files.
/api/v1/files/{file_id}/downloadDownloads a file with full RBAC enforcement and audit logging. Verifies user has access to the associated investigation/case. Supports range requests for large files. Returns file with appropriate content-type headers.
/api/v1/files/{file_id}/presigned-urlGenerates a time-limited presigned URL for direct file access from Cloudflare R2 storage. URL expires after configurable duration (default 1 hour). Useful for embedding files in reports or sharing with external tools.
/api/v1/admin/files/{file_id}/auditReturns complete audit trail for a specific file including all access events, downloads, and modifications. Admin or superuser only. Essential for chain of custody documentation.
Self-describing API endpoints for dynamic integration and documentation.
/api/v1/docs/endpointsReturns comprehensive documentation of all API endpoints including paths, methods, parameters, and response schemas. Used for generating client SDKs and integration documentation.
/api/v1/metadata/domainsReturns metadata about all available domains (entity types) including their properties, relationships, and UI configuration. Essential for building dynamic UIs that adapt to schema changes.
/api/v1/metadata/enumsReturns all enumeration types used in the API including status codes, priority levels, classification levels, and other categorical values. Used for populating dropdown menus.
/api/v1/metadata/providersReturns metadata about available OSINT and data providers including capabilities, rate limits, and required credentials. Used for configuring data source preferences.
Cryptographic audit trails with Merkle tree verification for tamper-evident logging.
/api/v1/audit/anchor/latestReturns the most recent Merkle tree root hash anchoring the audit log. Used for cryptographic verification of log integrity. Anchor is periodically published to blockchain for immutability.
/api/v1/audit/anchor/proof/{entry_id}Returns a Merkle inclusion proof for a specific audit entry. Proof can be independently verified against the published anchor. Essential for forensic chain of custody requirements.
/api/v1/mission-plansAI-assisted mission planning based on scenario description, target profiles, geographic constraints, and threat assessment. Returns structured plan with resource allocation, timeline, and contingencies.
/api/v1/mission-plans/{plan_id}Iteratively refines an existing mission plan based on new constraints or feedback. Maintains plan history for comparison. Supports partial updates to specific plan sections.
Evidence and audit
File, evidence, and audit endpoints need to preserve the same custody and integrity context shown in the operator workflow.
GRAPHQL
The primary GraphQL API (api.knogin.com/graphql) provides 100+ queries, 80+ mutations, and real-time subscriptions using the Strawberry GraphQL framework. GraphQL offers flexible data fetching, allowing clients to request exactly the data they need in a single request.
Domain
Create, manage, and track investigations with full lifecycle support including team assignment, file management, and progress tracking.
Domain
Full case management with templates, workflows, status tracking, profile linking, and bulk operations for efficient case handling.
Domain
Task management with assignments, checklists, dependencies, and progress tracking for structured investigation workflows.
Domain
Investigative notes with rich text, threading, and file attachments. Full chain of custody tracking for evidence-grade files.
Domain
Entity profile management for persons, organizations, and other entities with OSINT enrichment and relationship mapping.
Domain
Real-time alerting system with configurable monitors, severity levels, and decision workflows for threat detection.
Domain
Knowledge graph operations including pathfinding, centrality analysis, community detection, and link prediction for network intelligence.
Domain
Location-based queries, clustering, heatmaps, geofencing, and timeline analysis for geographic intelligence operations.
Domain
Create and manage customizable dashboards with panels, charts, and real-time metrics for operational awareness.
Domain
Global search with semantic capabilities, advanced filters, and saved queries for rapid intelligence discovery.
Domain
Court-admissible evidence tracking with chain of custody, integrity verification, and sealing for legal proceedings.
Domain
Open source intelligence queries across multiple providers for person, organization, phone, email, social media, vehicle, domain, IP, and cryptocurrency data.
Domain
Team management with member roles, permissions, and hierarchies for collaborative investigation operations.
Domain
Automated workflows with triggers, conditions, and actions for streamlined investigation processes.
Domain
AI-powered text analysis, entity extraction, summarization, translation, and document processing capabilities.
Domain
Real-time notifications with preferences, threaded comments, mentions, and reactions for team collaboration.
Example: Query Investigation with Cases
Pull investigation, case, and operator context in one request when the client needs a live workspace rather than a single object.
query InvestigationWorkspace($investigationId: ID!) {
investigation(id: $investigationId) {
id
title
status
createdAt
profiles {
id
name
type
riskScore
}
}
cases(investigationId: $investigationId) {
id
title
status
priority
assignedTo {
id
displayName
}
}
}Example: Create Alert Mutation
Mutation responses should return the core alert object plus the linked entities needed by triage and escalation workflows.
mutation CreateAlert($input: CreateAlertInput!) {
createAlert(input: $input) {
id
title
severity
confidence
createdAt
entities {
id
name
type
}
}
}GraphQL Endpoint
Use GraphQL when the client needs investigation state, linked entities, tasks, evidence, and dashboard context in one round trip.
https://api.knogin.com/graphqlWEBSOCKET
Real-time communication via WebSocket for live updates, GraphQL subscriptions, and collaboration features.
WebSocket Endpoints
GraphQL subscriptions and event streams are separate lanes. Use the one that matches whether the client needs object-level updates or broader event fanout.
wss://api.knogin.com/graphqlWebSocket endpoint for GraphQL subscriptions using the graphql-ws protocol. Supports all subscription operations including alert streams, investigation updates, and real-time collaboration.
wss://api.knogin.com/wsWebSocket endpoint for general real-time event streaming including investigation updates, system notifications, and user presence. Supports channel-based subscriptions.
Response Formats
Keep success, error, and rate-limit patterns explicit so integrators do not have to reverse engineer operational behavior from a preview environment.
{
"success": true,
"data": { ... },
"message": "Operation completed successfully",
"request_id": "req_abc123"
}{
"error": "VALIDATION_ERROR",
"message": "Invalid input parameters",
"code": "ERR_VALIDATION_001",
"details": {
"field": "email",
"reason": "Invalid email format"
}
}HTTP Status Codes
Common status codes returned by the API.
Rate Limits
API rate limits to ensure fair usage and system stability.
Standard Endpoints
1000 requests per minute
Authentication Endpoints
5 requests per minute (login, MFA verification)
Batch Operations
100 profiles per batch request, 10 for enrichment
File Uploads
50MB maximum file size
AI Processing
Subject to token limits per organization tier
Walk through auth posture, transport choices, rate behavior, and oversight assumptions with the team before a connector hits production traffic.