Com as APIs de administração, você pode automatizar tarefas de gestão da organização, como convidar usuários, analisar logs de auditoria, administrar projetos, gerenciar chaves de API, configurar limites e alertas de gastos, controlar a retenção de dados e gerenciar limites de taxa. Use essas APIs para automatizar rotinas internas, executar fluxos de trabalho de segurança e criar ferramentas operacionais que precisam funcionar fora do painel.
Para entender a diferença entre uma credencial administrativa, uma chave de projeto que pertence a um usuário e a conta de serviço de uma carga de trabalho, consulte Chaves de API e contas de serviço.
Para obter detalhes sobre os endpoints, consulte a referência da API de administração, que inclui as seções Chaves da API de administração, Convites, Usuários, Projetos, Limites de gastos e Logs de auditoria.
Para acessar esses endpoints, crie uma chave da API de administração. Essas chaves só podem ser usadas em endpoints de administração.
Os SDKs passaram a oferecer suporte às APIs de administração nas versões abaixo. Se você usa uma versão anterior, pode ser necessário atualizar o SDK.
- Node:
6.36.0
- Python:
2.34.0
- Go:
3.34.0
- Ruby:
0.61.0
- Java:
4.34.0
Defina OPENAI_ADMIN_KEY e inicialize o SDK da sua linguagem.
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")
)
Use as permissões de modelos do projeto para definir uma lista de modelos permitidos ou bloqueados. Defina mode como allow_list para permitir apenas os modelos da lista ou defina mode como deny_list para bloquear os modelos da lista e permitir os demais modelos disponíveis. Os IDs dos modelos precisam estar visíveis para a organização. Isso também vale para os IDs de snapshots de modelos que passaram por ajuste fino.
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)
Use o endpoint de limites de gastos para criar ou substituir o limite máximo de gastos mensais da organização. Informe o valor de threshold_amount em centavos. O exemplo a seguir define um limite mensal de US$ 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"
}'
Quando os gastos contabilizados atingem o limite máximo, as solicitações de API afetadas retornam o erro 429. Para saber mais, consulte o guia de limites de gastos.
Use os alertas de gastos do projeto para avisar sua equipe quando os gastos atingirem um valor definido. Informe em centavos o valor que aciona cada alerta.
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)
Use os controles de retenção de dados do projeto para aplicar a política de retenção da organização ou substituí-la por uma política específica do projeto. Defina retention_type como organization_default para herdar a configuração da organização.
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)
Use o endpoint de convites para enviar a um endereço de e-mail um convite para participar da organização.
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)
Use o endpoint de logs de auditoria para listar as ações recentes dos usuários e as alterações recentes na configuração da organização.
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
