> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Admin

> Connect Serval to OpenAI's Administration API to manage organization users, projects, API keys, spend controls, usage, and audit logs.

## 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](https://docs.serval.com/sections/integrations/openai.md), 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

| Capability | Description |
| - | - |
| User management | 6 ready-to-install workflows: List OpenAI Users (pages through every organization user, with an optional exact-email filter), Invite OpenAI User (organization membership only unless you name a project), List OpenAI Invites, Revoke OpenAI Invite, Update OpenAI User Role, and Remove OpenAI User. The role, removal, and revocation workflows look the person up by email and confirm the returned address before changing anything. |
| Project management | 3 workflows: List OpenAI Projects (archived projects excluded unless requested), Create OpenAI Project, and Archive OpenAI Project. |
| Security and spend | 4 workflows: List OpenAI Audit Logs (newest first, optionally limited to a time window, at most 1,000 events per run with a cursor to continue), List OpenAI Admin API Keys, Get OpenAI Cost Report (daily buckets plus per-currency totals for a time window), and Set OpenAI Organization Spend Limit. |
| Custom Admin API requests | Custom workflows reach the full modeled surface: users and their roles, invites, groups, custom roles, projects, project users, groups, service accounts, API keys, rate limits, model and hosted-tool permissions, data retention, spend limits and alerts, usage reports, costs, and audit logs. Authentication is handled automatically. |

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`](https://github.com/openai/openai-openapi) specification. See the [OpenAI Administration API reference](https://platform.openai.com/docs/api-reference/administration) 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](https://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.

> [!WARNING]
>
> 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.

> [!WARNING]
>
> 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:

| Health check | On success | On failure |
| - | - | - |
| List OpenAI Users | "Successfully connected to the OpenAI Admin API" | "Unable to list OpenAI organization users. Verify that you supplied an Admin API key." |
| List OpenAI Projects | "Successfully read OpenAI organization projects" | "Unable to read OpenAI organization projects with this Admin API key." |
| List OpenAI Audit Logs | "Successfully read OpenAI organization audit logs" | "Unable to read OpenAI organization audit logs. Audit logging may be turned off for this organization; an owner can turn it on in OpenAI's organization settings. Otherwise verify the Admin API key." |

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.

> [!TIP]
>
> 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

> **Admin and project keys aren't interchangeable**
>
> 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.

> **Admin keys are organization-wide credentials**
>
> 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.

> **Audit logs need to be turned on in OpenAI**
>
> 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.

> **Key creation isn't modeled, on purpose**
>
> 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.

> **Certificate uploads aren't modeled**
>
> OpenAI's certificate endpoints accept binary request bodies. Serval's typed workflow action is JSON-only, so certificate upload, activation, and deactivation are excluded.

> **Filtering audit logs by time**
>
> 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]=...`.

> **List endpoints are paginated**
>
> 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 and project roles**
>
> 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](mailto:support@serval.com)** for assistance with your OpenAI Admin integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.