Skip to main content

​
About OpenAI

OpenAI is the model provider behind Serval’s built-in text-generation workflow actions and many of Serval’s own AI features (Help Desk, Copilot, Catalyst, ticket categorization, the workflow builder, knowledge ingestion, and more). Unlike most integrations, OpenAI is not an application you connect - it works out of the box using Serval’s own OpenAI key and never appears in the application connect list. Optionally, an org admin can bring your organization’s own key (BYOK) on the AI Provider Keys page so every OpenAI call made on your organization’s behalf uses your key instead - including routing through an OpenAI-compatible endpoint such as OpenRouter or a self-hosted gateway. Authentication: Serval’s platform key by default (zero setup, nothing to connect). Optional org-level BYOK override: your own API key (stored encrypted at rest and only ever shown by its last four characters) plus an optional OpenAI-compatible base URL. Data sync: none. OpenAI is called on demand when a workflow action runs or a Serval AI feature needs a model - there is no entity sync, no member ingestion, no webhooks, and no polling.

​
What the OpenAI integration enables

CapabilityDescription
Prompt OpenAI actionSingle-prompt text generation in workflows. You provide a message (and optionally a model name) and the action returns the assistant’s text. Defaults to the gpt-4.1-2025-04-14 model. Preferred for single-turn prompts.
Create Chat Completion actionMulti-message chat in workflows - include a system prompt and conversation history and get back the assistant’s reply. Use when a single message isn’t enough.
Bring your own key (BYOK)Replace Serval’s platform OpenAI key with your organization’s own key for all OpenAI calls made on your behalf - both workflow actions and Serval’s backend AI features (Copilot, Help Desk guards and messages, ticket categorization, summarization and routing, Catalyst, Workflow Builder, knowledge ingestion).
OpenAI-compatible endpointsPoint the BYOK override at OpenRouter, a self-hosted gateway such as LiteLLM, or NVIDIA inference endpoints. Serval auto-detects the compatible API mode (Responses API vs Chat Completions) and automatically maps Serval’s model names for known gateways (currently NVIDIA inference endpoints).
Live key healthchecksEvery save of a key or custom base URL is validated with a real test request, and an on-demand model coverage healthcheck tests every model Serval plans to call through your endpoint - per-model pass/fail, latency, and the Serval features that use each model.

​
Get your credentials

You only need credentials if you want the optional BYOK override. With no override configured, the integration works immediately on Serval’s platform key and there is nothing to set up.
You need an OpenAI API secret key with permission to call model endpoints. A project-scoped key is fine - no OpenAI admin key is needed.
1

Sign in to the OpenAI platform

Sign in at platform.openai.com and select the project the key should belong to. Project keys carry their own usage tracking, rate limits, and spend limits - see Managing projects in the API platform.
2

Create a secret key

Go to API keys (also reachable via Settings, then your project, then API keys) and click Create new secret key. The OpenAI developer quickstart walks through this if you’re starting from scratch.
3

Copy the key immediately

OpenAI shows the secret key only once. Copy it right away and store it securely - follow OpenAI’s best practices for API key safety.
For a key your whole organization will run on, OpenAI’s production best practices cover rate limits and spend controls worth setting up front.

​
Connect in Serval

There is no connect flow for OpenAI - configuration lives on the AI Provider Keys page instead.
1

Open AI Provider Keys

Go to Admin settings > AI Provider Keys. The page is visible only to org admins, and it is rolled out per organization - if you don’t see it, contact support.
2

Start the override

On the OpenAI card, click Set override. (If an override already exists, click the pencil icon - Edit provider settings - instead.)
3

API key (required)

Paste your key into API key. It’s a password input and is trimmed automatically; Save is disabled while the field is blank when setting a new override. If validation fails you’ll see “openai key looks too short to be a real API key” (keys must be at least 16 characters) or “openai key must start with sk-” (only enforced when no custom base URL is set).When editing an existing override, leaving this field blank keeps the current key - the helper text reads “Paste a new provider API key, or leave this blank to keep the current key.”
4

API base URL (optional)

Leave blank to use OpenAI’s default endpoint (the placeholder shows https://api.openai.com/v1), or enter your gateway’s base URL. A Reset button clears the field so a save reverts to the default. The URL must be https with a host (http is allowed only for localhost); otherwise you’ll see messages like “openai base URL is invalid: URL must include a host” or “openai base URL is invalid: http is only allowed for localhost; use https for “[host]"". You cannot set a base URL before a key is configured - that attempt returns “openai: cannot update provider configuration until a key is configured for this provider”. A base URL change is probed too; if the probe fails, the save is rejected with “openai base URL healthcheck failed ([error code]): [error message]”.
5

API mode (read-only)

This field is auto-managed. It shows Responses API for the default endpoint (“Serval uses the Responses API for the default OpenAI endpoint.”) and Auto-detect when a custom base URL is entered (“Serval auto-detects the compatible API mode for custom OpenAI-compatible endpoints.”). The detected mode is stored after a passing healthcheck.
6

Save

Click Save override (or Save changes when editing an existing override). Serval runs a live test request against the effective endpoint before storing anything - if the probe fails, the save is rejected with “openai healthcheck failed ([error code]): [error message]” and nothing is stored. On success the key is encrypted at rest and replaces Serval’s platform key for your organization (allow up to 5 minutes for cached paths - see Gotchas).
Every save of a key or custom base URL (and every healthcheck) sends a small real, billable request to your provider. Clearing an override does not.

​
Verifying the connection

The OpenAI provider card gives you several signals:
  • Status pill. A configured override shows “Active - ends in [last four]”. With no override the pill reads “Platform key” and the card explains “Using Serval’s platform key”. The pill flips to “Checking…” while a probe runs and “Invalid key” if the last probe failed.
  • Save-time probe. Runs automatically whenever you save a key or a custom base URL. Success shows “Healthcheck passed in [number]ms. Detected [mode].” and a “Key saved and validated.” toast; failure shows “Healthcheck failed ([error code]): [error message]” and the save is rejected.
  • Run healthcheck (model coverage). The card’s Run healthcheck button “Checks each model Serval plans to call through this provider endpoint.” - one live probe per model, each row showing “Passed in [number]ms” or “Failed ([error code]): [error message]” plus “Used by [features]” so you can see which Serval features depend on that model. The button is disabled until a key is configured or typed. If you’ve typed a new key but not saved, the healthcheck tests the typed key without storing it.
Common failure messages are spelled out plainly: “Rate limited by provider. The key looks valid but exceeded a quota.” for quota issues, “Provider did not respond within 30s.” for timeouts, and “Provider returned status [number]: [body]” for other provider errors.
A green save probe but failing AI features usually means a model coverage gap: the save probe tests one model, but gateways often don’t host every model Serval uses. Click Run healthcheck to test all of them - any red row tells you exactly which model (and which Serval features) your endpoint can’t serve.

​
Gotchas and troubleshooting

This is by design - there is no Connect flow and no app instance for OpenAI. The workflow actions work with zero setup on Serval’s platform key, and the only customer-facing configuration is Admin settings > AI Provider Keys, visible to org admins on organizations where the page is enabled.
Serval validates with a live completion probe before persisting. A failed probe rejects the save with “openai healthcheck failed ([error code]): [error message]”, so a stored override is always one that passed a real request. The flip side: each save of a key or base URL and each Run healthcheck click sends a small billable request to your provider.
The path that serves the Prompt OpenAI and Create Chat Completion actions caches your resolved key for 5 minutes per organization, and Serval’s backend AI features use a similarly cached per-organization client with the same 5-minute lifetime. After rotating or clearing a key, calls may use the previous key for up to 5 minutes. Also note: if your override can’t be resolved for any reason, workflow calls silently fall back to Serval’s platform key rather than failing.
With a custom base URL set, the “openai key must start with sk-” check is skipped so gateway keys (OpenRouter, LiteLLM, NVIDIA) work. The 16-character minimum always applies. Conversely, you can’t configure a base URL or API mode until a key is in place.
Entering a custom base URL flips API mode to Auto-detect (Serval probes the Responses API first, then Chat Completions; NVIDIA inference endpoints go straight to Chat Completions). Clearing the base URL resets the mode to Responses API. Clearing the key also clears the base URL override.
Reasoning-capable models (gpt-5, o-series) can spend 5-15 seconds thinking before producing output, so the probe allows up to 30 seconds. A “Checking…” pill for several seconds is expected; only after 30 seconds will you see “Provider did not respond within 30s.”
When an override already exists, saving with a blank API key field updates only the base URL and preserves the stored key - the helper text says so explicitly. You never need to re-paste the key just to change the endpoint. (Save stays disabled until you change something.)
Prompt OpenAI defaults to gpt-4.1-2025-04-14 (you can pass a different model), and Create Chat Completion always uses that default. This is separate from the model lineup that Serval’s backend AI features use - the model coverage healthcheck covers the latter.
For most gateways (including OpenRouter), Serval sends its standard model names unchanged - your gateway must serve those exact names. Only NVIDIA inference endpoints get automatic model-name mapping; when a mapping applies, the healthcheck panel shows “Model mapping: [name]”, otherwise “No provider-specific model mapping detected.”
The integration does not manage your OpenAI organization: no member provisioning, no usage reporting, no admin-key requirement. It is exactly two LLM workflow actions plus the org-level key override.
Need help? Contact support@serval.com for assistance with your OpenAI integration.