> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/17.latest/backoffice/managing-connections.md).

# Managing Connections

Connections store the credentials needed to communicate with AI providers. Manage them through the backoffice UI.

## Viewing Connections

1. Navigate to the **AI** section > **Connections**.
2. The connection list shows all configured connections.
3. Click a connection to view or edit its details.

![The connections list showing the OpenAI connection with Active status](/files/1aOgDtR9DqsmHyv0SFdl)

## Creating a Connection

1. Click **Create Connection** in the Connections section.
2. Fill in the required fields:

| Field        | Description                      |
| ------------ | -------------------------------- |
| **Name**     | Display name for the connection  |
| **Alias**    | Unique identifier (used in code) |
| **Provider** | Select from installed providers  |

3. Configure provider-specific settings (varies by provider).
4. Click **Save**.

![The Select AI Provider dialog](/files/Xb2xCsnpqQtjz8FPVnsL)

![The Create Connection form with provider settings](/files/SpZKO6Z5oTCHqHG0e6DX)

### OpenAI Provider Settings

When using the OpenAI provider:

| Setting             | Description                                                                | Required |
| ------------------- | -------------------------------------------------------------------------- | -------- |
| **API Key**         | Your OpenAI API key                                                        | Yes      |
| **Organization ID** | Organization ID (if applicable)                                            | No       |
| **Base URL**        | Override the default OpenAI endpoint (for proxies or compatible providers) | No       |

## Using Configuration References

Instead of storing API keys directly in the database, use configuration references:

1. Add your API key to `appsettings.json` under the `Umbraco:AI:Secrets` section:

{% code title="appsettings.json" %}

```json
{
    "Umbraco": {
        "AI": {
            "Secrets": {
                "OpenAIApiKey": "sk-your-api-key-here"
            }
        }
    }
}
```

{% endcode %}

2. In the connection settings, enter `$Umbraco:AI:Secrets:OpenAIApiKey` as the API Key value.

The `$` prefix tells Umbraco.AI to resolve the value from configuration at runtime. References resolve from the `Umbraco:AI:Secrets` and `Umbraco:AI:Variables` sections by default - see [Configuration References](/ai-in-umbraco/17.latest/concepts/connections.md#configuration-references) for details.

{% hint style="success" %}
Configuration references keep sensitive values out of the database and allow different values per environment.
{% endhint %}

## Editing a Connection

1. Click on the connection in the list.
2. Modify the desired fields.
3. Click **Save**.

{% hint style="warning" %}
Changing a connection's provider is not supported. Create a new connection instead.
{% endhint %}

## Deleting a Connection

1. Open the connection you want to delete.
2. Click **Delete** in the actions menu.
3. Confirm the deletion.

{% hint style="danger" %}
Deleting a connection will break any profiles that depend on it. Consider deactivating the connection instead.
{% endhint %}

## Enabling and Disabling Connections

Use the **Active** toggle to enable or disable a connection:

* **Active** - Connection is available for use.
* **Inactive** - Connection is disabled; profiles using it will fail.

This is useful for:

* Temporarily disabling a connection without deleting it
* Rotating API keys (create new connection, disable old one)
* Testing failover scenarios

## Best Practices

1. **Use descriptive names** - "OpenAI Production" is better than "Connection 1".
2. **Use configuration references** - Keep API keys out of the database.
3. **Create separate connections per environment** - Don't share production keys in development.
4. **Use meaningful aliases** - They're used in code and should be readable.

## Related

* [Managing Profiles](/ai-in-umbraco/17.latest/backoffice/managing-profiles.md) - Create profiles using connections
* [Connections Concept](/ai-in-umbraco/17.latest/concepts/connections.md) - Deeper explanation of connections


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/ai-in-umbraco/17.latest/backoffice/managing-connections.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.