Platform
API Fleet
Expose external REST APIs to your agents as MCP tools. Tenants configure auth once; end users authenticate through connectors.
What it does#
API Fleet lets you register third-party HTTP APIs (Stripe, internal microservices, SaaS products) as service folders inside a Viksa project. Each folder holds one or more endpoints parsed from OpenAPI or added manually. Enabled endpoints become virtual tools that agents can call at runtime.
Core concepts#
| Concept | Description |
|---|---|
| Service folder | Named registry for a base URL plus a list of endpoints (GET /users, POST /charges, …). |
| Auth method | Reusable auth profile (API key, bearer, basic, OAuth2) shared across folders. |
| User Auth KMS | Your cloud KMS key (AWS, GCP, or Azure) used to encrypt end-user credentials — separate from project vault secrets. |
| Connect link | HTTPS URL sent in WhatsApp/Telegram chat; end users enter credentials or complete OAuth on Viksa-hosted pages. |
| headless_user_auth | Mongo collection storing per-user encrypted credentials keyed by connector user + service. |
Setup workflow#
- 1
Configure User Auth KMS
In API Fleet → Configure Auth KMS, pick AWS KMS, GCP Cloud KMS, or Azure Key Vault. Viksa runs an encrypt/decrypt round-trip before saving. - 2
Create auth methods
Define how end users authenticate (OAuth app registration, API key header name, etc.). Credentials are not entered here — only the schema. - 3
Create a service folder
Set the service base URL, optional description, and link a saved auth method (or leave public). Bulk-import from OpenAPI/Postman or add endpoints manually. - 4
Enable endpoints
Toggle endpoints on in the folder detail view. Disabled endpoints are not exposed as agent tools. - 5
End users connect via Volt
When an agent needs auth, Volt sends a connect link in chat. See Channel Hub for connector setup.
Authentication types#
| auth_type | End-user experience |
|---|---|
| none | None (public API — no per-user credentials) |
| api_key | API key — end user enters key on connect page |
| bearer | Bearer token — validated before save |
| basic | Basic auth — username/password validated before save |
| oauth2 | OAuth2 — connect link redirects to provider; tokens saved on callback |
End-user connect URLs#
Connect links are hosted on the Viksa public API domain — not your customer domain:
https://api.viksaai.com/headless/user-auth/connect?api_id=srv_…
user_id=connector_user_…
channel=whatsapp
project_id=prj_…
org_id=org_…
account_id=acc_…- OAuth2 — GET shows a button that redirects to the provider; callback hits
/headless/oauth/callback - API key / bearer / basic — GET renders a form; POST validates against the target API before KMS encrypt + save
- End users never paste secrets into chat — only open the link
KMS providers#
| encryption_mode | Provider |
|---|---|
| aws_kms | AWS KMS |
| gcp_kms | Google Cloud KMS |
| azure_keyvault | Azure Key Vault |
Data storage#
| Collection | Scope | Contents |
|---|---|---|
| headless_apis | project | Service folders and embedded endpoints |
| headless_auth_methods | project | Reusable auth schemas (no end-user secrets) |
| headless_auth_kms | project (1 doc) | KMS mode + config for credential encryption |
| headless_user_auth | project + user | Encrypted end-user credentials per connector identity |