Skip to main content

​
About OpenAI Admin

The OpenAI Admin integration connects Serval workflows to OpenAI’s organization-management API. The shipped workflows invite and remove users, change organization roles, list and revoke invites, create and archive projects, list Admin API keys, report costs, read audit logs, and set the organization spend limit. Custom workflows can also manage project members, groups and service accounts, revoke project keys, adjust project rate limits and model permissions, set spend alerts, and pull usage data. It’s built for the IT or platform team that owns the OpenAI organization: provisioning, off-boarding, key hygiene, and spend monitoring. This is separate from Serval’s OpenAI workflow actions, which generate text inside workflows. The Admin integration never calls a model. Authentication: OpenAI Admin API key. One key, created under the organization’s Admin keys settings, pasted into the connect form. Serval stores it securely and attaches it to every request; workflow code never sees the key. Standard project API keys can’t call administration endpoints, and Admin API keys can’t call inference endpoints. Data sync: On demand only. Serval calls OpenAI when a workflow runs. There is no background sync. What a workflow returns, such as a user list or audit events, stays in that run’s history and is visible to the people who can see the run.

​
What the integration enables

Read-only workflows run without approval. Invitations, role changes, removals, project changes, and spend-limit changes default to installer approval when installed. The typed action is generated from the official openai/openai-openapi specification. See the OpenAI Administration API reference for every endpoint.

​
Get your credentials

This integration requires an OpenAI Admin API key, which only an organization owner can create. It’s a different credential from the project API keys used to call models.
1

Sign in to the OpenAI Platform

Sign in at platform.openai.com as an organization owner.
2

Open the Admin keys page

Open Organization settings, then Admin keys.
3

Create an admin key

Select Create admin key and give it a descriptive name, for example Serval Production.
4

Copy the key immediately

OpenAI shows the secret once. Copy it right away and keep it in your secret manager until you connect the integration.
The key is displayed a single time, at creation. If you navigate away without copying it, create a new one.

​
Connect in Serval

1

Open the OpenAI Admin integration

In Serval, open Integrations, select All integrations, choose OpenAI Admin, and start a new connection.
2

Paste your admin key

Paste the full key into the Admin API Key field. It’s a password field, so the value stays hidden as you type.
3

Submit the form

Select Submit. Serval verifies the key by listing one organization user.
When you reopen the connection settings later, the saved key appears masked and you can’t type over it directly. Saving without touching the key keeps the stored key. To rotate it, select the pencil icon (or Replace) next to the masked value, paste the complete new key, and save in the same edit.

​
Verifying the connection

When you submit the form, Serval verifies the key by listing one organization user. The integration also ships three health checks you can run from the connection page: The most common cause of the first two failing is pasting a project API key instead of an admin key. The audit-log check also fails when nobody has turned on audit logging for the organization, even with a valid key.
If the health check is green but a workflow that makes changes (inviting users, archiving projects, setting a spend limit) appears stuck rather than failed, check your pending Serval approvals. Every mutating workflow in this integration defaults to installer approval and waits for sign-off before it runs.

​
Gotchas and troubleshooting

A project API key can’t manage the organization, and an Admin API key can’t call the Responses, Chat Completions, or other inference APIs. Use the OpenAI provider configuration for model calls and this integration for administration.
An Admin API key can remove users, archive projects, revoke other keys, and change spend and security settings across the whole organization. Treat it as the most sensitive credential in your stack, restrict who can connect or rotate it, and keep the approval defaults on destructive workflows.
OpenAI records organization audit events only after an organization owner turns on audit logging in the organization settings. Until then the List OpenAI Audit Logs health check fails and the audit-log workflow returns an error, even with a valid Admin API key.
Creating an Admin API key, a service account, or a service-account key returns a new secret. Those operations are excluded from the typed action, and Serval’s proxy refuses them even when a custom workflow builds the request by hand, so credentials can never land in workflow run history. Create keys in the OpenAI console and use Serval for inventory and revocation.
OpenAI’s certificate endpoints accept binary request bodies. Serval’s typed workflow action is JSON-only, so certificate upload, activation, and deactivation are excluded.
The audit-log endpoint takes an effective_at object with gt, gte, lt, and lte members in Unix seconds, and array filters named with brackets such as project_ids[]. Pass them as the typed action expects. Serval sends every array as bracketed repeated keys, the shape OpenAI’s own SDKs use, and range objects as effective_at[gte]=....
Most list responses return has_more and a last_id cursor to pass as after. The costs and usage endpoints return next_page to pass as page instead. The shipped workflows page through every result for you.
Organization roles are owner and reader, and project roles are owner and member. The shipped Update OpenAI User Role workflow changes the organization role. To change a project role, send a custom request to the project users endpoint. Custom roles, and assigning or revoking them, go through the roles endpoints under /v1/organization/roles.
Need help? Contact support@serval.com for assistance with your OpenAI Admin integration.