Repository Public
1# Admin APIs23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Admin APIs let you automate organization management workflows such as user invitations, audit log review, project administration, API key management, spend limits and alerts, data retention, and rate limit operations. Use them for back-office automation, security workflows, and operational tooling that should run outside the dashboard.67For endpoint details, see the [Administration API reference](https://developers.openai.com/api/reference/administration/overview), including [Admin API keys](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/admin_api_keys), [Invites](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/invites), [Users](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/users), [Projects](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/projects), [Spend limits](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/spend_limit), and [Audit logs](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/audit_logs).89## Use an Admin API key with the SDK1011To access these endpoints, [create an Admin API key](https://platform.openai.com/settings/organization/admin-keys). Admin API keys cannot be used for non-administration endpoints.1213Support for Admin APIs was added in these SDK versions, which may require updating your SDK version:1415- Node: `6.36.0`16- Python: `2.34.0`17- Go: `3.34.0`18- Ruby: `0.61.0`19- Java: `4.34.0`2021Set `OPENAI_ADMIN_KEY`, then initialize the SDK for your language.2223Set up the SDK with an Admin API key2425```javascript26import OpenAI from "openai";2728const client = new OpenAI({29 adminAPIKey: process.env.OPENAI_ADMIN_KEY,30});31```3233```python34import os35from openai import OpenAI3637client = OpenAI(38 admin_api_key=os.environ["OPENAI_ADMIN_KEY"],39)40```4142```go43package main4445import (46 "os"4748 "github.com/openai/openai-go/v3"49 "github.com/openai/openai-go/v3/option"50)5152func main() {53 client := openai.NewClient(54 option.WithAdminAPIKey(os.Getenv("OPENAI_ADMIN_KEY")),55 )5657 _ = client58}59```6061```java62import com.openai.client.OpenAIClient;63import com.openai.client.okhttp.OpenAIOkHttpClient;6465OpenAIClient client =66 OpenAIOkHttpClient.builder().adminApiKey(System.getenv("OPENAI_ADMIN_KEY")).build();67```6869```ruby70require "openai"7172openai = OpenAI::Client.new(73 admin_api_key: ENV.fetch("OPENAI_ADMIN_KEY")74)75```767778## Restrict model access for projects7980Use project model permissions to set an allowlist or denylist for a project. Set `mode` to `allow_list` to allow only the listed models, or set `mode` to `deny_list` to block the listed models while allowing other available models. Model IDs must be visible to the organization, including visible fine-tuned model snapshots.8182Set a project model allowlist/denylist8384```javascript85const modelPermissions =86 await client.admin.organization.projects.modelPermissions.update("proj_abc", {87 mode: "allow_list",88 model_ids: ["gpt-4.1", "o3"],89 });9091console.log(modelPermissions.mode);92```9394```python95model_permissions = client.admin.organization.projects.model_permissions.update(96 "proj_abc",97 mode="allow_list",98 model_ids=["gpt-4.1", "o3"],99)100101print(model_permissions.mode)102```103104```go105ctx := context.Background()106107modelPermissions, err := client.Admin.Organization.Projects.ModelPermissions.Update(108 ctx,109 "proj_abc",110 openai.AdminOrganizationProjectModelPermissionUpdateParams{111 Mode: openai.AdminOrganizationProjectModelPermissionUpdateParamsModeAllowList,112 ModelIDs: []string{"gpt-4.1", "o3"},113 },114)115if err != nil {116 panic(err)117}118119println(modelPermissions.Mode)120```121122```java123import com.openai.models.admin.organization.projects.modelpermissions.ModelPermissionUpdateParams;124import com.openai.models.admin.organization.projects.modelpermissions.ProjectModelPermissions;125import java.util.List;126127ProjectModelPermissions modelPermissions =128 client129 .admin()130 .organization()131 .projects()132 .modelPermissions()133 .update(134 "proj_abc",135 ModelPermissionUpdateParams.builder()136 .mode(ModelPermissionUpdateParams.Mode.ALLOW_LIST)137 .modelIds(List.of("gpt-4.1", "o3"))138 .build());139140System.out.println(modelPermissions.mode());141```142143```ruby144model_permissions = openai.admin.organization.projects.model_permissions.update(145 "proj_abc",146 mode: :allow_list,147 model_ids: ["gpt-4.1", "o3"]148)149150puts(model_permissions.mode)151```152153154## Set an organization spend limit155156Use the [Spend Limits endpoint](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/spend_limit) to create or replace your organization's monthly hard spend limit. Set `threshold_amount` in cents. The following example sets a $100 monthly limit:157158```bash159curl -X POST https://api.openai.com/v1/organization/spend_limit \160 -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \161 -H "Content-Type: application/json" \162 -d '{163 "threshold_amount": 10000,164 "currency": "USD",165 "interval": "month"166 }'167```168169When tracked spend reaches a hard limit, affected API requests return a `429` error. For details, see the [spend limits guide](https://developers.openai.com/api/docs/guides/spend-limits).170171## Manage spend limit alerts172173Use project spend alerts to notify your team when project spend reaches a threshold. Threshold amounts are specified in cents.174175Create a project spend limit alert176177```javascript178const spendAlert = await client.admin.organization.projects.spendAlerts.create(179 "proj_abc",180 {181 currency: "USD",182 interval: "month",183 notification_channel: {184 recipients: ["billing@example.com"],185 type: "email",186 subject_prefix: "[OpenAI spend]",187 },188 threshold_amount: 50000,189 }190);191192console.log(spendAlert.id);193```194195```python196spend_alert = client.admin.organization.projects.spend_alerts.create(197 "proj_abc",198 currency="USD",199 interval="month",200 notification_channel={201 "recipients": ["billing@example.com"],202 "type": "email",203 "subject_prefix": "[OpenAI spend]",204 },205 threshold_amount=50000,206)207208print(spend_alert.id)209```210211```go212ctx := context.Background()213214spendAlert, err := client.Admin.Organization.Projects.SpendAlerts.New(215 ctx,216 "proj_abc",217 openai.AdminOrganizationProjectSpendAlertNewParams{218 Currency: openai.AdminOrganizationProjectSpendAlertNewParamsCurrencyUsd,219 Interval: openai.AdminOrganizationProjectSpendAlertNewParamsIntervalMonth,220 NotificationChannel: openai.AdminOrganizationProjectSpendAlertNewParamsNotificationChannel{221 Recipients: []string{"billing@example.com"},222 Type: "email",223 SubjectPrefix: openai.String("[OpenAI spend]"),224 },225 ThresholdAmount: 50000,226 },227)228if err != nil {229 panic(err)230}231232println(spendAlert.ID)233```234235```java236import com.openai.models.admin.organization.projects.spendalerts.ProjectSpendAlert;237import com.openai.models.admin.organization.projects.spendalerts.SpendAlertCreateParams;238239ProjectSpendAlert spendAlert =240 client241 .admin()242 .organization()243 .projects()244 .spendAlerts()245 .create(246 "proj_abc",247 SpendAlertCreateParams.builder()248 .currency(SpendAlertCreateParams.Currency.USD)249 .interval(SpendAlertCreateParams.Interval.MONTH)250 .notificationChannel(251 SpendAlertCreateParams.NotificationChannel.builder()252 .addRecipient("billing@example.com")253 .subjectPrefix("[OpenAI spend]")254 .build())255 .thresholdAmount(50000L)256 .build());257258System.out.println(spendAlert.id());259```260261```ruby262spend_alert = openai.admin.organization.projects.spend_alerts.create(263 "proj_abc",264 currency: :USD,265 interval: :month,266 notification_channel: {267 recipients: ["billing@example.com"],268 type: :email,269 subject_prefix: "[OpenAI spend]"270 },271 threshold_amount: 50_000272)273274puts(spend_alert.id)275```276277278## Manage data retention279280Use project data retention controls to override or inherit the organization's retention policy for a project. Set `retention_type` to `organization_default` to inherit the organization setting.281282Set project data retention283284```javascript285const dataRetention =286 await client.admin.organization.projects.dataRetention.update("proj_abc", {287 retention_type: "organization_default",288 });289290console.log(dataRetention.type);291```292293```python294data_retention = client.admin.organization.projects.data_retention.update(295 "proj_abc",296 retention_type="organization_default",297)298299print(data_retention.type)300```301302```go303ctx := context.Background()304305dataRetention, err := client.Admin.Organization.Projects.DataRetention.Update(306 ctx,307 "proj_abc",308 openai.AdminOrganizationProjectDataRetentionUpdateParams{309 RetentionType: openai.AdminOrganizationProjectDataRetentionUpdateParamsRetentionTypeOrganizationDefault,310 },311)312if err != nil {313 panic(err)314}315316println(dataRetention.Type)317```318319```java320import com.openai.models.admin.organization.projects.dataretention.DataRetentionUpdateParams;321import com.openai.models.admin.organization.projects.dataretention.ProjectDataRetention;322323ProjectDataRetention dataRetention =324 client325 .admin()326 .organization()327 .projects()328 .dataRetention()329 .update(330 "proj_abc",331 DataRetentionUpdateParams.builder()332 .retentionType(DataRetentionUpdateParams.RetentionType.ORGANIZATION_DEFAULT)333 .build());334335System.out.println(dataRetention.type());336```337338```ruby339data_retention = openai.admin.organization.projects.data_retention.update(340 "proj_abc",341 retention_type: :organization_default342)343344puts(data_retention.type)345```346347348## Invite a user by email349350Use the Invites endpoint to send an organization invitation to an email address.351352Invite a user by email353354```javascript355const invite = await client.admin.organization.invites.create({356 email: "user@example.com",357 role: "reader",358});359360console.log(invite.id);361```362363```python364invite = client.admin.organization.invites.create(365 email="user@example.com",366 role="reader",367)368369print(invite.id)370```371372```go373ctx := context.Background()374375invite, err := client.Admin.Organization.Invites.New(ctx, openai.AdminOrganizationInviteNewParams{376 Email: "user@example.com",377 Role: openai.AdminOrganizationInviteNewParamsRoleReader,378})379if err != nil {380 panic(err)381}382383println(invite.ID)384```385386```java387import com.openai.models.admin.organization.invites.Invite;388import com.openai.models.admin.organization.invites.InviteCreateParams;389390Invite invite =391 client392 .admin()393 .organization()394 .invites()395 .create(396 InviteCreateParams.builder()397 .email("user@example.com")398 .role(InviteCreateParams.Role.READER)399 .build());400401System.out.println(invite.id());402```403404```ruby405invite = openai.admin.organization.invites.create(406 email: "user@example.com",407 role: :reader408)409410puts(invite.id)411```412413414## Retrieve audit logs415416Use the Audit Logs endpoint to list recent user actions and configuration changes for the organization.417418Retrieve audit logs419420```javascript421const auditLogs = await client.admin.organization.auditLogs.list({422 limit: 10,423});424425console.log(auditLogs.data);426```427428```python429audit_logs = client.admin.organization.audit_logs.list(limit=10)430431for audit_log in audit_logs.data:432 print(audit_log.id)433```434435```go436ctx := context.Background()437438auditLogs, err := client.Admin.Organization.AuditLogs.List(ctx, openai.AdminOrganizationAuditLogListParams{439 Limit: openai.Int(10),440})441if err != nil {442 panic(err)443}444445for _, auditLog := range auditLogs.Data {446 println(auditLog.ID)447}448```449450```java451import com.openai.models.admin.organization.auditlogs.AuditLogListParams;452453var page =454 client455 .admin()456 .organization()457 .auditLogs()458 .list(AuditLogListParams.builder().limit(10L).build());459460page.data().forEach(auditLog -> System.out.println(auditLog.id()));461```462463```ruby464audit_logs = openai.admin.organization.audit_logs.list(limit: 10)465466(audit_logs.data || []).each do |audit_log|467 puts(audit_log.id)468end469```