# AI connections (https://docs.akollo.com/en/ai/connections)



## What it is [#what-it-is]

By default, Akollo's AI features use the models Akollo provides. An admin can instead connect an AI provider with your
organization's own key ("bring your own key") and choose which of that provider's models does which job.

Supported providers: OpenRouter, Anthropic, OpenAI, Google AI, Azure OpenAI, Amazon Bedrock and Google Vertex AI,
plus your own model server, directly or through the AI Connector.

<Mermaid
  title="Where an AI request goes"
  chart="`flowchart LR
A[AI feature in Akollo] --> B{Model chosen for this job}
B -->|Default| C[Models Akollo provides]
B -->|Active connection| D{Data allowed on this connection?}
D -->|Yes| E[Your provider or model server]
D -->|Restricted data| F[Stays on the institution's own server]`"
/>

## Adding a connection [#adding-a-connection]

<Steps>
  <Step>
    ### Open the connections page [#open-the-connections-page]

    Open **Settings › AI › Connections**.
  </Step>

  <Step>
    ### Enter the provider and key [#enter-the-provider-and-key]

    Under **Add a connection**, pick the **Provider**, give the connection a **Name** and paste the **API key**. For
    Azure OpenAI and Vertex AI, also enter the **Address** your provider gives you. For Amazon Bedrock, enter the
    **Region** (for example eu-central-1).
  </Step>

  <Step>
    ### Choose which data may go through it [#choose-which-data-may-go-through-it]

    Under **Data allowed**, pick one level: **Public data only**, **Up to internal data** or **Up to confidential
    data**. The most sensitive (restricted) data never goes to an outside provider. Information marked restricted stays
    on the institution's own server. Then choose **Add connection**.
  </Step>
</Steps>

| Data level   | Can go through an outside connection?                            |
| ------------ | ---------------------------------------------------------------- |
| Public       | Yes, at every level                                              |
| Internal     | Yes, with **Up to internal data** or **Up to confidential data** |
| Confidential | Yes, only with **Up to confidential data**                       |
| Restricted   | Never. It stays on the institution's own server                  |

<Callout type="info" title="Note">
  The key is stored encrypted and is never shown again, not even to admins. To change it, use **Replace key**, then test the
  connection again.
</Callout>

## Testing and activating [#testing-and-activating]

<Steps>
  <Step>
    ### Find models [#find-models]

    **Find models** lists the models your key can use.
  </Step>

  <Step>
    ### Test a model [#test-a-model]

    **Test** runs a short check on the model you choose: answers in Turkish, structured answers and using a tool. You can
    activate the connection only after it passes.
  </Step>

  <Step>
    ### Activate [#activate]

    **Activate** turns the connection on. In live organizations, another admin has to approve the activation on the same
    page. Until then the connection shows **Waiting for a second admin**. The other admin chooses **Approve activation**
    or **Reject**. The person who asked cannot approve it.
  </Step>
</Steps>

<Mermaid
  title="Connection status"
  chart="`flowchart LR
A[Draft] -->|Test passes, Activate| B{Live organization?}
B -->|No| D[Active]
B -->|Yes| C[Waiting for a second admin]
C -->|Approve activation| D
C -->|Reject| F[Not activated]
D -->|Disable| E[Disabled]`"
/>

| Status                         | Meaning                                                             |
| ------------------------------ | ------------------------------------------------------------------- |
| **Draft**                      | Added, not yet active. Find models and test it here.                |
| **Waiting for a second admin** | Activation requested in a live organization. Another admin decides. |
| **Active**                     | In use. Its tested models can be chosen for jobs.                   |
| **Disabled**                   | Turned off for good.                                                |

## Your own model server [#your-own-model-server]

If your organization runs its own model server (for example llama.cpp or vLLM), add it as **Own model server** with
its HTTPS address. A key is optional.

* The address must be on your installation's list of allowed destinations.
* Akollo never connects to private or reserved addresses unless the installation allows that server.
* From a cloud installation, an address on the institution's private network is not accepted as an outside connection.
  Use the AI Connector instead.

## AI Connector [#ai-connector]

If the model server is inside a closed network, use the **AI Connector**. It is a small program that runs next to the
model server and connects out to Akollo, so no inbound connection is needed.

<Steps>
  <Step>
    ### Create the connector [#create-the-connector]

    Under **Add an AI Connector**, give it a name.
  </Step>

  <Step>
    ### Copy the token [#copy-the-token]

    Copy the token that appears. It is shown only once.
  </Step>

  <Step>
    ### Start the connector [#start-the-connector]

    Start the connector next to your model server with that token. The connection card shows whether the connector is
    online.
  </Step>
</Steps>

<Mermaid
  title="AI Connector: only outbound connections"
  chart="`flowchart LR
subgraph Closed network
M[Model server] --- K[AI Connector]
end
K -->|Connects out with its token| A[Akollo]`"
/>

<Callout type="warn" title="Warning">
  **New token** replaces the token. The old one stops working at once, so restart the connector with the new token.
</Callout>

## Choosing models for jobs [#choosing-models-for-jobs]

Under **Which model does which job**, choose for each job either the models Akollo provides or a model of an active
connection, then choose **Save**. The jobs are:

* **Routing**
* **Safety check**
* **Everyday answers**
* **Planning and complex work**
* **Search**

Only active connections, and the models their test found, can be chosen. Until you add a connection, AI runs on the
models Akollo provides.

## Costs [#costs]

Requests through your own connection are billed to you by the provider. They do not use your organization's Akollo AI
tokens.

<Screenshot src="/screens/en/settings-usage.webp" alt="Usage page with the AI input tokens meter selected and a budget field" caption="Usage: Akollo AI tokens are metered here. Requests through your own connection do not count against them." />

## Turning a connection off [#turning-a-connection-off]

**Disable** turns a connection off for good. Jobs that used it go back to the models Akollo provides.

## Who can manage connections [#who-can-manage-connections]

Organization owners and admins. Every change is recorded with who made it and when. In a support session, the
connections can be viewed but not changed.

## FAQ [#faq]

<Accordions type="single">
  <Accordion title="Can I see the API key again after saving it?">
    No. The key is stored encrypted and is never shown again, not even to admins. Use **Replace key** to change it.
  </Accordion>

  <Accordion title="Can restricted data be sent to my own provider?">
    No. Restricted data never goes to an outside provider. It stays on the institution's own server.
  </Accordion>

  <Accordion title="Why can’t I activate a connection?">
    The connection must pass **Test** first. In live organizations, a second admin must also approve the activation; the
    person who asked cannot approve it.
  </Accordion>

  <Accordion title="Do requests through my connection use our AI tokens?">
    No. The provider bills you directly, and those requests do not use your organization's Akollo AI tokens.
  </Accordion>

  <Accordion title="What happens when I disable a connection?">
    It is turned off for good, and the jobs that used it go back to the models Akollo provides.
  </Accordion>

  <Accordion title="Our model server is in a closed network. Do we need to open an inbound port?">
    No. The AI Connector runs next to the model server and connects out to Akollo.
  </Accordion>
</Accordions>

## Related pages [#related-pages]

* [Who can use assistance, and AI tokens](/en/ai/access-and-tokens)
* [Running the model in the institution](/en/ai/on-prem)
* [What assistance can see](/en/ai/privacy)