Admin APIs

Admin APIs

Admin APIs를 사용하면 조직 관리 워크플로우(사용자 초대, 감사 로그 검토, 프로젝트 관리, API 키 관리, 지출 한도 및 알림, 데이터 보존, rate limit 작업 등)를 자동화할 수 있어요. 대시보드 밖에서 실행해야 하는 백오피스 자동화, 보안 워크플로우, 운영 도구에 활용하세요.

출처: 문서

본문

Admin APIs를 사용하면 사용자 초대, 감사 로그 검토, 프로젝트 관리, API 키 관리, 지출 한도 및 알림, 데이터 보존, rate limit 작업 같은 조직 관리 워크플로우를 자동화할 수 있어요. 대시보드 밖에서 실행되어야 하는 백오피스 자동화, 보안 워크플로우, 운영 도구에 사용하세요.

엔드포인트에 대한 자세한 내용은 Administration API reference를 참고하세요. 여기에는 Admin API keys, Invites, Users, Projects, Spend limits, Audit logs가 포함돼요.

SDK에서 Admin API 키 사용하기

이 엔드포인트에 접근하려면 Admin API 키를 생성하세요. Admin API 키는 관리(administration)가 아닌 엔드포인트에는 사용할 수 없어요.

Admin 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를 초기화하세요.

Admin API 키로 SDK 설정하기

import OpenAI from "openai";

const client = new OpenAI({
  adminAPIKey: proces...KEY,
});

import os
from openai import OpenAI

client = OpenAI(
    admin_api_key=os.environ["OPENAI_ADMIN_KEY"],
)

package main

import (
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	client := openai.NewClient(
		option.WithAdminAPIKey(os.Getenv("OPENAI_ADMIN_KEY")),
	)

	_ = client
}

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

OpenAIClient client =
    OpenAIOkHttpClient.builder().adminApiKey(System.getenv("OPENAI_ADMIN_KEY")).build();

require "openai"

openai = OpenAI::Client.new(
  admin_api_key: ENV.fetch("OPENAI_ADMIN_KEY")
)

프로젝트의 모델 접근 제한하기

프로젝트 모델 권한(project model permissions)을 사용해 프로젝트에 대해 허용 목록(allowlist) 또는 차단 목록(denylist)을 설정할 수 있어요. mode를 allow_list로 설정하면 나열된 모델만 허용하고, mode를 deny_list로 설정하면 나열된 모델을 차단하면서 다른 사용 가능한 모델은 허용해요. 모델 ID는 조직에 표시 가능해야 하며, 표시 가능한 파인튜닝된 모델 스냅샷도 포함돼요.

프로젝트 모델 허용 목록/차단 목록 설정하기

const modelPermissions =
  await client.admin.organization.projects.modelPermissions.update("proj_abc", {
    mode: "allow_list",
    model_ids: ["gpt-4.1", "o3"],
  });

console.log(modelPermissions.mode);

model_permissions = client.admin.organization.projects.model_permissions.update(
    "proj_abc",
    mode="allow_list",
    model_ids=["gpt-4.1", "o3"],
)

print(model_permissions.mode)

ctx := 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)
}

println(modelPermissions.Mode)

import 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());

model_permissions = openai.admin.organization.projects.model_permissions.update(
  "proj_abc",
  mode: :allow_list,
  model_ids: ["gpt-4.1", "o3"]
)

puts(model_permissions.mode)

조직 지출 한도 설정하기

Spend Limits 엔드포인트를 사용해 조직의 월간 하드 지출 한도(hard spend limit)를 생성하거나 교체하세요. threshold_amount는 센트 단위로 지정해요. 다음 예시는 $100 월 한도를 설정해요:

curl -X POST https://api.openai.com/v1/organization/spend_limit \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold_amount": 10000,
    "currency": "USD",
    "interval": "month"
  }'

추적된 지출이 하드 한도에 도달하면, 해당 API 요청은 429 오류를 반환해요. 자세한 내용은 spend limits guide를 참고하세요.

지출 한도 알림 관리하기

프로젝트 지출 알림(project spend alerts)을 사용해 프로젝트 지출이 임계값에 도달할 때 팀에 알릴 수 있어요. 임계값 금액은 센트 단위로 지정해요.

프로젝트 지출 한도 알림 만들기

const spendAlert = await client.admin.organization.projects.spendAlerts.create(
  "proj_abc",
  {
    currency: "USD",
    interval: "month",
    notification_channel: {
      recipients: ["[email protected]"],
      type: "email",
      subject_prefix: "[OpenAI spend]",
    },
    threshold_amount: 50000,
  }
);

console.log(spendAlert.id);

spend_alert = client.admin.organization.projects.spend_alerts.create(
    "proj_abc",
    currency="USD",
    interval="month",
    notification_channel={
        "recipients": ["[email protected]"],
        "type": "email",
        "subject_prefix": "[OpenAI spend]",
    },
    threshold_amount=50000,
)

print(spend_alert.id)

ctx := 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{"[email protected]"},
			Type:          "email",
			SubjectPrefix: openai.String("[OpenAI spend]"),
		},
		ThresholdAmount: 50000,
	},
)
if err != nil {
	panic(err)
}

println(spendAlert.ID)

import 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("[email protected]")
                        .subjectPrefix("[OpenAI spend]")
                        .build())
                .thresholdAmount(50000L)
                .build());

System.out.println(spendAlert.id());

spend_alert = openai.admin.organization.projects.spend_alerts.create(
  "proj_abc",
  currency: :USD,
  interval: :month,
  notification_channel: {
    recipients: ["[email protected]"],
    type: :email,
    subject_prefix: "[OpenAI spend]"
  },
  threshold_amount: 50_000
)

puts(spend_alert.id)

데이터 보존 관리하기

프로젝트 데이터 보존 컨트롤을 사용해 프로젝트에 대한 조직 보존 정책을 재정의하거나 상속할 수 있어요. retention_type을 organization_default로 설정하면 조직 설정을 상속해요.

프로젝트 데이터 보존 설정하기

const dataRetention =
  await client.admin.organization.projects.dataRetention.update("proj_abc", {
    retention_type: "organization_default",
  });

console.log(dataRetention.type);

data_retention = client.admin.organization.projects.data_retention.update(
    "proj_abc",
    retention_type="organization_default",
)

print(data_retention.type)

ctx := 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)

import 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());

data_retention = openai.admin.organization.projects.data_retention.update(
  "proj_abc",
  retention_type: :organization_default
)

puts(data_retention.type)

이메일로 사용자 초대하기

Invites 엔드포인트를 사용해 이메일 주소로 조직 초대를 보내세요.

이메일로 사용자 초대하기

const invite = await client.admin.organization.invites.create({
  email: "[email protected]",
  role: "reader",
});

console.log(invite.id);

invite = client.admin.organization.invites.create(
    email="[email protected]",
    role="reader",
)

print(invite.id)

ctx := context.Background()

invite, err := client.Admin.Organization.Invites.New(ctx, openai.AdminOrganizationInviteNewParams{
	Email: "[email protected]",
	Role:  openai.AdminOrganizationInviteNewParamsRoleReader,
})
if err != nil {
	panic(err)
}

println(invite.ID)

import 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("[email protected]")
                .role(InviteCreateParams.Role.READER)
                .build());

System.out.println(invite.id());

invite = openai.admin.organization.invites.create(
  email: "[email protected]",
  role: :reader
)

puts(invite.id)

감사 로그 검색하기

Audit Logs 엔드포인트를 사용해 조직의 최근 사용자 작업과 설정 변경을 나열하세요.

감사 로그 검색하기

const auditLogs = await client.admin.organization.auditLogs.list({
  limit: 10,
});

console.log(auditLogs.data);

audit_logs = client.admin.organization.audit_logs.list(limit=10)

for audit_log in audit_logs.data:
    print(audit_log.id)

ctx := 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 {
	println(auditLog.ID)
}

import com.openai.models.admin.organization.auditlogs.AuditLogListParams;

var page =
    client
        .admin()
        .organization()
        .auditLogs()
        .list(AuditLogListParams.builder().limit(10L).build());

page.data().forEach(auditLog -> System.out.println(auditLog.id()));

audit_logs = openai.admin.organization.audit_logs.list(limit: 10)

(audit_logs.data || []).each do |audit_log|
  puts(audit_log.id)
end

더 알아보기 (Learn more)

관련 문서: 지출 한도(spend limits) 가이드와 Administration API 레퍼런스를 참고하세요.