> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bota.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider Integrations

> Administer project-scoped ASR and LLM provider credentials

Provider integrations let a project use its own ASR or LLM provider key for
supported processing routes. The Bota API key authenticates the administrator;
the provider key is a separate secret stored for provider requests. Saving a
key does not select a model, enable automatic processing, or approve a provider
route for regulated data.

Reads require a secret project key or a restricted key with
`integrations:read`. Changes and explicit credential tests require
`integrations:write`. These permissions are project-scoped. Device and end-user
tokens cannot administer integrations.

> [!NOTE]
>
> This authored guide describes the packaged CLI/MCP compatibility source preview.
> It does not extend this site's published OpenAPI projection. Additional REST
> schema publication and matching-backend availability remain separate.
>
> The public [CLI `0.2.0-beta.0` cohort](https://docs.bota.dev/cli) includes the integration commands
> and local MCP forwarding below. Hosted admission still requires the matching
> deployed backend. The REST examples below describe source compatibility; client
> publication or documentation availability does not establish an environment's
> deployed version or provider approval.

## Configure a provider

Enter a provider key through [Platform](https://platform.bota.dev) or a trusted
server-side secret store. For terminal administration, pass the value to the
CLI through standard input. Never put a provider key in a command argument or
ask an assistant to collect, copy or rotate the raw key in a conversation.

```bash CLI — read a protected secret file theme={null}
bota integrations set asr deepgram --key-stdin < /run/secrets/deepgram-api-key
bota integrations get asr deepgram
bota integrations test asr deepgram
```

The secret file belongs to your deployment or local secret-management process;
its contents are not an example credential. `--key-stdin` is accepted only for
`set` and `rotate`. Input is bounded to 16 KiB and a 30-second deadline. It is
not echoed or included in command output.

`set` creates or replaces the current project's entry for the provider and
enables it. Use `rotate` to replace the key on an existing integration by ID.
Disabling keeps the saved configuration; deleting removes it from Bota. Neither
action revokes the key at the external provider. Review the affected processing
configuration before changing or removing an entry.

Configure provider/model selection and automatic-processing settings separately
through the corresponding processing request or [configuration](https://docs.bota.dev/guides/hierarchical-config.md).

## REST compatibility source preview

All paths below are relative to `https://api.bota.dev/v1`. Provider type is
`asr` or `llm`; the provider name must be supported for that type. Examples
include `asr/deepgram` and `llm/openai`.

| Method and path | Input | Success |
| - | - | - |
| `GET /integrations` | No body | `200 { data: Integration[] }`, without cursor pagination |
| `GET /integrations/{providerType}/{providerName}` | Provider identifiers | `200 Integration`; `404` if no entry exists |
| `POST /integrations` | `provider_type`, `provider_name`, `api_key` | `201 Integration`; create or replace the provider's project entry |
| `PATCH /integrations/{id}` | Optional `api_key`, `is_enabled` | `200 Integration` |
| `DELETE /integrations/{id}` | Integration ID | `204`, empty body |
| `DELETE /integrations/{providerType}/{providerName}` | Provider identifiers | `204`, empty body |
| `POST /integrations/{providerType}/{providerName}/test` | JSON object, with optional `api_key` | `200 { success, message }`; policy refusal can return `409` |

### Credential writes

Create or replace using a JSON object supplied by your trusted backend:

```json Example shape — inject the credential from your secret store theme={null}
{
  "provider_type": "asr",
  "provider_name": "deepgram",
  "api_key": "<provider-key-from-your-secret-store>"
}
```

PATCH can replace the key, change `is_enabled`, or do both. Credentials are
write-only: reads return metadata rather than the raw or encrypted key. An
uncertain write response does not prove failure; retrieve the entry's metadata
and reconcile before intentionally repeating a change.

### Metadata

REST integration objects include `id`, `project_id`, `provider_type`,
`provider_name`, `is_enabled`, nullable `last_used_at` and `last_error`, and
`created_at` / `updated_at` timestamps. These are stored observations, not a
fresh processing or provider-health result. Treat server diagnostic text as
potentially sensitive and avoid copying it into assistant prompts or logs.

CLI and MCP present a safer metadata projection: they expose a boolean
`has_error` instead of raw `last_error`. They do not reveal the stored key.

## CLI commands

Use the integration ID returned by a list or get operation for ID-based
commands. Commands use your selected Bota project credentials and the same
read/write admission as REST.

```bash theme={null}
bota integrations list
bota integrations get asr deepgram
bota integrations set asr deepgram --key-stdin < /run/secrets/deepgram-api-key
bota integrations rotate <id> --key-stdin < /run/secrets/replacement-provider-key
bota integrations enable <id>
bota integrations disable <id>
bota integrations delete <id>
bota integrations delete-provider asr deepgram
bota integrations test asr deepgram
```

Delete commands perform the requested deletion; inspect the project and entry
before running them. Test uses the stored key and never asks for a raw key in
arguments. A reported test failure is not a successful health check merely
because the API responded with HTTP `200`.

## Hosted and local MCP

Developer MCP tools support bounded administration without accepting provider
secrets. In the default legacy local mode, these five tools forward to the hosted
MCP implementation with the current project credential. Older local tools retain
their existing implementation and result shapes. Legacy discovery lists all
five integration tools; the hosted server authorizes each forwarded invocation.

The separate [opt-in hosted mode](https://docs.bota.dev/mcp-server.md#local-stdio-bridge-to-hosted-mcp)
forwards discovery and invocation for the complete authorized hosted inventory.
Its discovery filters the current credential's scopes, just as a direct hosted
connection does. Neither mode treats a visible tool as permission to invoke it,
and neither changes the requirement to enter provider keys outside chat.

| Workflow | Hosted MCP | Local MCP | Required scope |
| - | - | - | - |
| List safe metadata | `list_integrations` | `list_integrations` | `integrations:read` |
| Read one provider's safe metadata | `get_integration` | `get_integration` | `integrations:read` |
| Test the stored key | `test_integration` | `test_integration` | `integrations:write` |
| Enable or disable by ID | `update_integration` | `update_integration` | `integrations:write` |
| Delete by ID | `delete_integration` | `delete_integration` | `integrations:write` |
| Enter or replace a raw provider key | Use Platform or CLI standard input | Use Platform or CLI standard input | No secret-entry MCP tool |

`get_integration` and `test_integration` take `provider_type` and
`provider_name`. `update_integration` accepts only `id` and `is_enabled`;
`delete_integration` takes `id`. There is no MCP `api_key` input or credential
readback. Provider administration is unavailable to the end-user MCP tier.

## What a test proves

A test makes a basic provider request with the selected stored key, subject to
the applicable provider and policy checks. It can consume provider capacity.
The provider request has a 10-second deadline, refuses redirects, and is not
automatically retried. That deadline is separate from CLI standard-input and
client-request deadlines.
The REST form also permits a supplied key for a trusted server-side test;
CLI/MCP deliberately test the stored key only.

Success reports basic credential validity for that check. It does not verify
the full transcription, summary or Ask pipeline, every model permission,
billing availability, or HIPAA/GDPR and other provider-route approvals.

Credential testing is currently unavailable for projects with HIPAA or GDPR
mode enabled: the shared REST/Platform/MCP guard returns HTTP `409` with
`provider_route_not_approved` before contacting the provider. There is no
approved credential-test route today, and approving a processing route does
not authorize this separate authentication check. Do not disable the project's
protection mode to bypass that refusal.

Keep tests explicit. Do not automatically repeat an uncertain provider call
or infer that a stored error flag explains its underlying cause. See
[Authentication](https://docs.bota.dev/authentication.md#restricted-keys-and-operation-scopes) and
[regulated processing guidance](https://docs.bota.dev/legal/hipaa.md) for the separate admission
boundaries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.