Integration setup
Use AKOS setup guidance to connect OAuth apps, bot installations, API keys, webhooks, MCP servers, and LLM providers.
AKOS keeps provider-specific setup instructions in the integration setup registry. The assistant, Connections screen, and CLI read that registry instead of duplicating setup steps in static docs.
Use Home (Assistant) when you want guided setup in conversation. It can explain what happens inside AKOS, what you must complete in the external service, which permissions are requested, and which health check confirms the connection.
Use the CLI when you need the same setup data for automation or review:
Each guide can include:
- The preferred setup mode: OAuth, app or bot installation, guided secret, platform-managed setup, or fallback.
- The setup CTA and summary shown in product surfaces.
- Required scopes or permissions.
- External credential links when a provider needs an API key.
- The health-check method AKOS should run after setup.
- Assistant instructions for safe wording and redaction.
For tenant setup, prefer OAuth or app installation when available. Ask for API keys only when the registry says a guided secret is the right path. Never paste raw secrets into chat output; store them through Connections or the vault-backed CLI flow.
The Connections screen is still the main place to connect, verify, rotate, and remove provider credentials.
For OAuth-protected Knowledge sources, complete the provider connection here first, then add the source in the Knowledge screen.
For scoped keys that let external apps call /v1/automations/*, use Connections › External apps and read Public automation API.
Provider setup checklist
Use the registry guide first, then prepare the provider-side object that matches its setup mode:
| Setup mode | Provider-side setup | AKOS setup |
|---|---|---|
| OAuth | Create an OAuth app, add the AKOS callback URL, select the registry scopes, and keep client credentials in the operator vault. | Connect from Connections or the assistant; verify with the provider health check. |
| App or bot installation | Create/install the provider app for the target workspace, org, guild, or site; grant only the registry permissions. | Complete the installation flow and confirm the connected account/workspace metadata. |
| Guided secret or API key | Create a scoped key for a service account, rotateable bot user, or sandbox tenant. | Store the key through Connections or the vault-backed CLI flow; never paste it into chat. |
| MCP server | Configure the MCP server URL/command, auth policy, and egress allowlist. | Register the MCP connection, then run a tool-list/read-only smoke before enabling write actions. |
| DB connection | Create a least-privilege DB user, network allowlist, TLS settings, and read/write role according to the workflow. | Store the DSN/parts as a secret and run a metadata/readiness check before any mutation workflow. |
When the setup is ambiguous, the assistant should ask which tenant/workspace, environment, provider account, and permission level to use before it renders a connect action.
Live validation
Use the provider health check in Connections after setup. Health checks record only provider, status, and safe proof metadata; tokens, client secrets, API keys, and private keys are redacted from reports and logs.
Related screens
| Need | Go to |
|---|---|
| Connect / verify credentials | Connections |
| Guided setup in chat | Home (Assistant) |
| OAuth knowledge sources | Knowledge |
| External automation keys | Public automation API |
| CLI reference | Command reference |