관리자 API를 사용하면 사용자 초대, 감사 로그 검토, 프로젝트 및 API 키 관리, 지출 한도 및 알림 설정, 데이터 보존, 요청 한도 관리 등 조직 관리 워크플로우를 자동화할 수 있습니다. 대시보드 외부에서 실행해야 하는 백오피스 자동화 작업, 보안 워크플로우, 운영 도구에 관리자 API를 활용하세요.
관리용 자격 증명, 사용자가 소유한 프로젝트 키, 워크로드의 서비스 계정이 어떻게 다른지는 API 키 및 서비스 계정을 참고하세요.
엔드포인트에 대한 자세한 내용은 관리자 API 레퍼런스를 참고하세요. 관리자 API 키, 초대, 사용자, 프로젝트, 지출 한도, 감사 로그 항목에서 각 엔드포인트의 사용법을 확인할 수 있습니다.
이 엔드포인트에 액세스하려면 관리자 API 키를 생성하세요. 관리자 API 키는 관리용 엔드포인트에서만 사용할 수 있습니다.
관리자 API는 다음 SDK 버전부터 지원됩니다. 이전 버전을 사용 중이라면 SDK를 업데이트해야 할 수 있습니다.
- Node:
6.36.0
- Python:
2.34.0
- Go:
3.34.0
- Ruby:
0.61.0
- Java:
4.34.0
OPENAI_ADMIN_KEY를 설정한 다음, 사용 중인 언어에 맞는 SDK를 초기화하세요.
1
2
3
4
5import OpenAI from "openai";
const client = new OpenAI({
adminAPIKey: process.env.OPENAI_ADMIN_KEY,
});
1
2
3
4
5
6import os
from openai import OpenAI
client = OpenAI(
admin_api_key=os.environ["OPENAI_ADMIN_KEY"],
)
1
2
3
4
5
6
7
8
9
10
11
12import (
"context"
"fmt"
"os"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/option"
)
client := openai.NewClient(
option.WithAdminAPIKey(os.Getenv("OPENAI_ADMIN_KEY")),
)
1
2
3
4
5
6import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.admin.organization.auditlogs.AuditLogListParams;
OpenAIClient client =
OpenAIOkHttpClient.builder().adminApiKey(System.getenv("OPENAI_ADMIN_KEY")).build();
1
2
3
4
5require "openai"
openai = OpenAI::Client.new(
admin_api_key: ENV.fetch("OPENAI_ADMIN_KEY")
)
프로젝트의 모델 권한 설정에서 허용 목록이나 차단 목록을 지정하세요. mode를 allow_list로 설정하면 목록에 있는 모델만 허용됩니다. mode를 deny_list로 설정하면 목록에 있는 모델은 차단되고 사용 가능한 나머지 모델은 허용됩니다. 모델 ID는 조직에서 조회할 수 있어야 하며, 조직에서 조회할 수 있는 파인튜닝 모델 스냅샷의 ID도 사용할 수 있습니다.
1
2
3
4
5
6
7const modelPermissions =
await client.admin.organization.projects.modelPermissions.update("proj_abc", {
mode: "allow_list",
model_ids: ["gpt-4.1", "o3"],
});
console.log(modelPermissions.mode);
1
2
3
4
5
6
7model_permissions = client.admin.organization.projects.model_permissions.update(
"proj_abc",
mode="allow_list",
model_ids=["gpt-4.1", "o3"],
)
print(model_permissions.mode)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15ctx := context.Background()
modelPermissions, err := client.Admin.Organization.Projects.ModelPermissions.Update(
ctx,
"proj_abc",
openai.AdminOrganizationProjectModelPermissionUpdateParams{
Mode: openai.AdminOrganizationProjectModelPermissionUpdateParamsModeAllowList,
ModelIDs: []string{"gpt-4.1", "o3"},
},
)
if err != nil {
panic(err)
}
fmt.Println(modelPermissions.Mode)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import com.openai.models.admin.organization.projects.modelpermissions.ModelPermissionUpdateParams;
import com.openai.models.admin.organization.projects.modelpermissions.ProjectModelPermissions;
import java.util.List;
ProjectModelPermissions modelPermissions =
client
.admin()
.organization()
.projects()
.modelPermissions()
.update(
"proj_abc",
ModelPermissionUpdateParams.builder()
.mode(ModelPermissionUpdateParams.Mode.ALLOW_LIST)
.modelIds(List.of("gpt-4.1", "o3"))
.build());
System.out.println(modelPermissions.mode());
1
2
3
4
5
6
7model_permissions = openai.admin.organization.projects.model_permissions.update(
"proj_abc",
mode: :allow_list,
model_ids: ["gpt-4.1", "o3"]
)
puts(model_permissions.mode)
지출 한도 엔드포인트를 사용해 조직의 월별 지출 상한을 새로 설정하거나 기존 상한을 교체하세요. threshold_amount에는 금액을 센트 단위로 지정하세요. 다음 예시는 월별 지출 상한을 100달러로 설정합니다.
12345678curl -X POST https://api.openai.com/v1/organization/spend_limit \
-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"threshold_amount": 10000,
"currency": "USD",
"interval": "month"
}'
집계된 지출액이 상한에 도달하면 해당 한도가 적용되는 API 요청은 429 오류를 반환합니다. 자세한 내용은 지출 한도 가이드를 참고하세요.
프로젝트 지출 알림을 설정하면 프로젝트 지출액이 지정한 기준 금액에 도달할 때 팀에 알림을 보낼 수 있습니다. 기준 금액은 센트 단위로 지정하세요.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15const spendAlert = await client.admin.organization.projects.spendAlerts.create(
"proj_abc",
{
currency: "USD",
interval: "month",
notification_channel: {
recipients: ["billing@example.com"],
type: "email",
subject_prefix: "OpenAI spend",
},
threshold_amount: 50000,
}
);
console.log(spendAlert.id);
1
2
3
4
5
6
7
8
9
10
11
12
13spend_alert = client.admin.organization.projects.spend_alerts.create(
"proj_abc",
currency="USD",
interval="month",
notification_channel={
"recipients": ["billing@example.com"],
"type": "email",
"subject_prefix": "OpenAI spend",
},
threshold_amount=50000,
)
print(spend_alert.id)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21ctx := context.Background()
spendAlert, err := client.Admin.Organization.Projects.SpendAlerts.New(
ctx,
"proj_abc",
openai.AdminOrganizationProjectSpendAlertNewParams{
Currency: openai.AdminOrganizationProjectSpendAlertNewParamsCurrencyUsd,
Interval: openai.AdminOrganizationProjectSpendAlertNewParamsIntervalMonth,
NotificationChannel: openai.AdminOrganizationProjectSpendAlertNewParamsNotificationChannel{
Recipients: []string{"billing@example.com"},
Type: "email",
SubjectPrefix: openai.String("OpenAI spend"),
},
ThresholdAmount: 50000,
},
)
if err != nil {
panic(err)
}
fmt.Println(spendAlert.ID)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import com.openai.models.admin.organization.projects.spendalerts.ProjectSpendAlert;
import com.openai.models.admin.organization.projects.spendalerts.SpendAlertCreateParams;
ProjectSpendAlert spendAlert =
client
.admin()
.organization()
.projects()
.spendAlerts()
.create(
"proj_abc",
SpendAlertCreateParams.builder()
.currency(SpendAlertCreateParams.Currency.USD)
.interval(SpendAlertCreateParams.Interval.MONTH)
.notificationChannel(
SpendAlertCreateParams.NotificationChannel.builder()
.addRecipient("billing@example.com")
.subjectPrefix("OpenAI spend")
.build())
.thresholdAmount(50000L)
.build());
System.out.println(spendAlert.id());
1
2
3
4
5
6
7
8
9
10
11
12
13spend_alert = openai.admin.organization.projects.spend_alerts.create(
"proj_abc",
currency: :USD,
interval: :month,
notification_channel: {
recipients: ["billing@example.com"],
type: :email,
subject_prefix: "OpenAI spend"
},
threshold_amount: 50_000
)
puts(spend_alert.id)
프로젝트의 데이터 보존 설정에서 조직의 보존 정책을 상속하거나 프로젝트에 별도 정책을 적용할 수 있습니다. 조직 설정을 상속하려면 retention_type을 organization_default로 설정하세요.
1
2
3
4
5
6const dataRetention =
await client.admin.organization.projects.dataRetention.update("proj_abc", {
retention_type: "organization_default",
});
console.log(dataRetention.type);
1
2
3
4
5
6data_retention = client.admin.organization.projects.data_retention.update(
"proj_abc",
retention_type="organization_default",
)
print(data_retention.type)
1
2
3
4
5
6
7
8
9
10
11
12
13
14ctx := context.Background()
dataRetention, err := client.Admin.Organization.Projects.DataRetention.Update(
ctx,
"proj_abc",
openai.AdminOrganizationProjectDataRetentionUpdateParams{
RetentionType: openai.AdminOrganizationProjectDataRetentionUpdateParamsRetentionTypeOrganizationDefault,
},
)
if err != nil {
panic(err)
}
println(dataRetention.Type)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import com.openai.models.admin.organization.projects.dataretention.DataRetentionUpdateParams;
import com.openai.models.admin.organization.projects.dataretention.ProjectDataRetention;
ProjectDataRetention dataRetention =
client
.admin()
.organization()
.projects()
.dataRetention()
.update(
"proj_abc",
DataRetentionUpdateParams.builder()
.retentionType(DataRetentionUpdateParams.RetentionType.ORGANIZATION_DEFAULT)
.build());
System.out.println(dataRetention.type());
1
2
3
4
5
6data_retention = openai.admin.organization.projects.data_retention.update(
"proj_abc",
retention_type: :organization_default
)
puts(data_retention.type)
초대 엔드포인트를 사용해 사용자의 이메일 주소로 조직 초대장을 보내세요.
1
2
3
4
5
6const invite = await client.admin.organization.invites.create({
email: "user@example.com",
role: "reader",
});
console.log(invite.id);
1
2
3
4
5
6invite = client.admin.organization.invites.create(
email="user@example.com",
role="reader",
)
print(invite.id)
1
2
3
4
5
6
7
8
9
10
11ctx := context.Background()
invite, err := client.Admin.Organization.Invites.New(ctx, openai.AdminOrganizationInviteNewParams{
Email: "user@example.com",
Role: openai.AdminOrganizationInviteNewParamsRoleReader,
})
if err != nil {
panic(err)
}
fmt.Println(invite.ID)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import com.openai.models.admin.organization.invites.Invite;
import com.openai.models.admin.organization.invites.InviteCreateParams;
Invite invite =
client
.admin()
.organization()
.invites()
.create(
InviteCreateParams.builder()
.email("user@example.com")
.role(InviteCreateParams.Role.READER)
.build());
System.out.println(invite.id());
1
2
3
4
5
6invite = openai.admin.organization.invites.create(
email: "user@example.com",
role: :reader
)
puts(invite.id)
감사 로그 엔드포인트를 사용해 조직의 최근 사용자 작업과 설정 변경 내역을 조회하세요.
1
2
3
4
5const auditLogs = await client.admin.organization.auditLogs.list({
limit: 10,
});
console.log(auditLogs.data);
1
2
3
4audit_logs = client.admin.organization.audit_logs.list(limit=10)
for audit_log in audit_logs.data:
print(audit_log.id)
1
2
3
4
5
6
7
8
9
10
11
12ctx := context.Background()
auditLogs, err := client.Admin.Organization.AuditLogs.List(ctx, openai.AdminOrganizationAuditLogListParams{
Limit: openai.Int(10),
})
if err != nil {
panic(err)
}
for _, auditLog := range auditLogs.Data {
fmt.Println(auditLog.ID)
}
1
2
3
4
5
6
7
8var page =
client
.admin()
.organization()
.auditLogs()
.list(AuditLogListParams.builder().limit(10L).build());
page.data().forEach(auditLog -> System.out.println(auditLog.id()));
1
2
3
4
5audit_logs = openai.admin.organization.audit_logs.list(limit: 10)
(audit_logs.data || []).each do |audit_log|
puts(audit_log.id)
end
