Connecting to OpenAI

An OpenAI Connection lets Magic Suite use OpenAI on your own account, with your own API key. It is used by the OpenAi report macros, and from version 4.6 it can also power Merlin for your whole tenant.

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

What you need

Field	Value
URL	The API base address. For OpenAI itself this is https://api.openai.com/v1
Password	Your API key. Magic Suite stores it encrypted and never shows it again.
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. Go to Admin, then Connections.
2. Add a Connection and choose the OpenAI type.
3. Give it a name your colleagues will recognise, such as OpenAI production.
4. Set the URL to your endpoint, usually https://api.openai.com/v1
5. Paste the API key into the password field.
6. In Configuration, name the model you want, for example {"Model": "gpt-4o-mini"}
7. Save, then use the connection test to confirm Magic Suite can reach it.

Tip: the model you name should be one your OpenAI account can actually use. Accounts differ in which models they are granted, and asking for one you do not have produces a failure at the moment someone runs a report, not when you save the connection.

Using an endpoint 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 password field, because Magic Suite treats an empty credential as an incomplete Connection.

Anthropic's Claude models work this way too. Anthropic publishes an endpoint that speaks the OpenAI chat completions API, so you can reach Claude with this same OpenAI connection type by setting the URL to https://api.anthropic.com/v1 and using an Anthropic API key. The steps, including how to create the key, are on Connecting to Anthropic (Claude).

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

Tenant Connections and personal Connections

A tenant Connection is shared by everyone in your tenant and is created under Admin. 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
Authentication or 401 errors	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.
Model not found	The model named in Configuration is not one this account can use. Check the spelling and the account's model access.
Occasional failures under load	Rate limits. These are set by your provider against your account, not by Magic Suite.
Connection saves but the test fails	Usually the URL. Check it is the API base address and includes the version segment where the service expects one.

Using this Connection for Merlin (coming in version 4.6)

From version 4.6 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. See Configuring Merlin for your tenant.