Connecting to OpenAI

An OpenAI Connection lets Magic Suite use OpenAI, or a service that speaks the same API, on your own account with your own API key. It can power Merlin for your whole Tenant.

You need a Tenant Administrator role to create a Tenant Connection.

What you need

Field	Value
Connection Type	OpenAI
URL	The API base address. For OpenAI itself this is https://api.openai.com/v1, filled in for you you choose the type
API Key	Your API key. Magic Suite stores it encrypted.
Configuration	A small piece of JSON naming the model, for example {"Model": "gpt-4o-mini"}

Creating an API key at OpenAI

1. Sign in at platform.openai.com. This is the developer platform, which is a different account area from the ChatGPT app
2. Make sure the account has billing set up and some credit. A key on an account with no credit is accepted when you create it and then fails on the first real request
3. Open the API keys page from the left-hand menu and choose to create a new secret key
4. Give it a name that says where it is used, such as Magic Suite production. When you later see a list of keys you will want to know which is which
5. If your account offers project scoping, create the key inside a project used only for Magic Suite. That keeps its spending and its rate limits separate from anything else you run
6. Copy the key immediately. OpenAI shows the value once, at creation, and never again

Note: paste the key straight into the Magic Suite Connection and nowhere else. Do not put it in a ticket, a chat message or an email, and do not save it to a file first. If it does end up somewhere it should not, delete the key at OpenAI and create a new one, which takes a few seconds and is the only reliable fix.

Creating the Connection in Magic Suite

1. In the Admin app, go to Connections
2. Add a Connection and choose the OpenAI type
3. Give it a name your colleagues will recognise, such as OpenAI production
4. Check the URL, usually https://api.openai.com/v1
5. Paste the API key into the API Key field
6. In Configuration, name the model you want, for example {"Model": "gpt-4o-mini"}. For a gpt-5.6 or gpt-6 model, also add "ReasoningEffort": "none", for example {"Model": "gpt-6", "ReasoningEffort": "none"}. Using this Connection for Merlin, below, says why
7. Save. The AI Tool Calling column on the Connections page then shows whether the model calls, and Test Connection in the Connection's form checks it again at any time

Note: if the form shows a User Name field as well, leave it blank and paste the API key into the field below it, whether that is labelled API Key or Password. If the URL fills in as https://openai.com/, change it to https://api.openai.com/v1.

Tip: the model you name should be one your OpenAI account can actually use. Accounts differ in which models they are granted. The Connection test checks the address and the key, not the model, so a model you do not have shows as Tool calling: not supported, and fails when someone uses it. The Connection's statistics, described below, say whether the model is available to your key.

Using a service other than OpenAI

The Connection works with anything that speaks the OpenAI chat completions API, not only OpenAI itself. That includes Azure OpenAI, a gateway your organisation runs, and self-hosted servers such as Ollama.

Set the URL to that service's base address and use whatever credential it expects. If the service needs no credential, put any non-empty placeholder in the API Key field, because Magic Suite treats an empty credential as an incomplete Connection.

Azure OpenAI has two addresses. For Merlin, use https://name.openai.azure.com/openai/v1, with your deployment name as the Model. The [OpenAi.Complete:] report macro uses the resource address on its own, https://name.openai.azure.com/, and does not work with OpenAI itself. Testing the Connection checks each address the way it is used.

For Anthropic's Claude models, use the Anthropic (Claude) Connection type instead. The steps, including how to create the key, are on the Anthropic (Claude) Connections help page.

Note: not every compatible service implements the whole API. The one capability worth checking is tool calling, because Merlin relies on it to reach your data. A service that accepts a request carrying tools and then ignores them will answer confidently with nothing behind the answer, so check what Testing the Connection reports.

Version and statistics (coming in the next 4.6 release)

On the Connections page in the Admin app, the Version column shows the model the Connection uses. For OpenAI that is the model named in Configuration. For Azure OpenAI it is the model a deployment is named after, with its date where Azure lists only one, for example gpt-4.1-mini-2025-04-14 for a deployment called gpt-4.1-mini. A deployment named anything else is shown followed by (deployment).

The statistics icon on the same row opens the Connection's statistics. They show:

• Whether the service offers the configured model to this API key: Available, Not available, Cannot be checked, or No model configured
• The model's release date, and the date it retires where the service has announced one. A date within 90 days is shown in amber, and one that has passed in red
• For Azure OpenAI, the region the resource runs in, and the model's lifecycle and capabilities. The capabilities describe the model, and are not necessarily available in Merlin
• The models available to this API key, newest first. For Azure OpenAI only the models that can chat are listed

Note: Cannot be checked is normal for an Azure OpenAI deployment whose name is not a model name. Azure lists the models a resource can use, not its deployments, so Magic Suite cannot confirm a deployment name either way.

Magic Suite refreshes the statistics about every half hour, and Update in the statistics pop-up refreshes them at once. They come from the service's list of models, which OpenAI and Azure do not charge for, so they use no tokens.

Tenant Connections and Personal Connections

A Tenant Connection is shared by everyone in your Tenant and is created in the Admin app. A Personal Connection belongs to one person and is theirs alone.

For anything the whole Tenant relies on, use a Tenant Connection. A Personal Connection used for shared work bills one individual for everyone's usage, and stops working the day that person leaves. Merlin will only use a Tenant Connection for this reason.

Looking after the key

• Set a spending limit at OpenAI. Magic Suite cannot cap what your provider charges you
• Use separate keys for production and for testing, so you can revoke one without stopping the other
• Replace the key periodically. Create the new key, update the Connection, confirm it works, then delete the old key at OpenAI
• Revoke immediately if a key may have been exposed. A key cannot be repaired, only replaced

If it does not work

What you see	Usual cause
The test says the API key was not accepted (status code 401)	The key is wrong, has been revoked, or belongs to a different account. Create a fresh key.
Works at first, then stops	The account has run out of credit, or a spending limit has been reached.
The test passes but tool calling shows not supported	Usually the model named in Configuration is not one this account can use. Check the spelling and the account's model access. For gpt-5.6 and gpt-6 models, see Using this Connection for Merlin below.
The statistics say Not available	The service does not list the model named in Configuration for this API key. Check the spelling, or choose one from the models available to the key in the same pop-up.
Occasional failures under load	Rate limits. These are set by your provider against your account, not by Magic Suite.
The test fails with status code 404	Usually the URL. Check it is the API base address and includes the version segment where the service expects one, such as https://api.openai.com/v1

Using this Connection for Merlin

On a Merlin Pro or Merlin Enterprise plan, a Tenant Administrator can point Merlin at an OpenAI Connection, so that Merlin's answers are generated on your own account rather than on Panoramic Data's. In the Admin app, go to Tenant, then Merlin AI, choose the Connection, read the consent statement, tick the box below it, and Save. See Configuring Merlin for your Tenant.

Tip: OpenAI's gpt-5.6 and gpt-6 models only call tools when no reasoning effort is requested, so for those add "ReasoningEffort": "none" next to the Model in the Configuration. Without it, the test shows Tool calling: not supported, and Merlin answers without reading your data.