OpenWikiopenai/openai-node

Admin and organization reference

Purpose and Scope

The admin and organization surface in openai-node is for automation that operates above a single model request. Instead of creating responses, embeddings, or files for an end-user workflow, these resources let an internal tool manage organization membership, project boundaries, spend controls, certificates, usage reporting, and administrative keys. The official Admin APIs guidance frames this area as back-office automation for security, operational tooling, project administration, API key management, audit review, data retention, and spend alerts. In the SDK, those capabilities are exposed through the generated client.admin.organization namespace rather than through the model-specific resource groups.

Sources: src/resources/admin/organization/index.ts, src/resources/admin/organization/projects/index.ts, tests/api-resources/admin/organization/usage.test.ts

Use this page when you need to find the TypeScript entry points and type names for organization-level or project-level administration. The important distinction is scope. Organization resources affect the whole organization or report across projects, while project resources represent nested administration for a specific project, such as project API keys, project users, project groups, service accounts, model permissions, hosted tool permissions, rate limits, and project spend alerts. The generated exports are intentionally narrow: the index files collect resource classes, parameter types, response types, and pagination page types so application code can rely on stable public names instead of reaching into implementation details.

Sources: src/resources/admin/organization/index.ts, src/resources/admin/organization/projects/index.ts

Admin APIs require administrative credentials. The official docs recommend creating an Admin API key and constructing the Node client with adminAPIKey, commonly from OPENAI_ADMIN_KEY; those keys are meant for administration endpoints and not for ordinary model endpoints. The repository's generated usage tests instantiate OpenAI with both apiKey and adminAPIKey, then call organization usage methods through client.admin.organization.usage. That test pattern is useful because it shows the SDK path, the client option name, and the promise helper behavior shared by generated request methods.

Sources: tests/api-resources/admin/organization/usage.test.ts

Relevant Source Files

  • api.md - Generated API reference for the SDK; use it as the broad method and type reference alongside the generated resource modules.
  • src/resources/admin/organization/index.ts - Aggregates organization-level admin resource exports, including admin API keys, audit logs, certificates, data retention, groups, invites, projects, roles, spend alerts, usage, and users.
  • src/resources/admin/organization/projects/index.ts - Aggregates project-level admin resource exports, including project API keys, certificates, groups, hosted tool permissions, model permissions, rate limits, roles, service accounts, spend alerts, and users.
  • tests/api-resources/admin/organization/usage.test.ts - Confirms generated usage methods are reachable from client.admin.organization.usage, accept required and optional query parameters, and expose response helper methods.

System-to-Code Mapping

At the top level, src/resources/admin/index.ts exposes Admin and Organization, and the organization index re-exports the concrete organization resource families. The organization namespace includes AdminAPIKeys, AuditLogs, Certificates, DataRetention, Groups, Invites, Projects, Roles, SpendAlerts, Usage, and Users. It also exports typed models and request parameter types such as AdminAPIKeyCreateParams, CertificateUpdateParams, GroupCreateParams, InviteListParams, RoleUpdateParams, SpendAlertListParams, UsageCompletionsParams, and UserUpdateParams. These names tell you the public contract: resources own operations, parameter types describe inputs, response types describe outputs, and page types mark paginated lists.

Sources: src/resources/admin/organization/index.ts

The project sub-namespace mirrors the same generated design but applies it within a project boundary. src/resources/admin/organization/projects/index.ts exports APIKeys, Certificates, DataRetention, Groups, HostedToolPermissions, ModelPermissions, Projects, RateLimits, Roles, ServiceAccounts, SpendAlerts, and Users. It also exports project-specific models such as ProjectAPIKey, ProjectDataRetention, ProjectGroup, ProjectHostedToolPermissions, ProjectModelPermissions, ProjectRateLimit, ProjectServiceAccount, ProjectSpendAlert, and ProjectUser. If a workflow is about who or what can act inside one project, start in this namespace rather than the organization-wide user, group, or role collections.

Sources: src/resources/admin/organization/projects/index.ts

Think of the generated admin model as a hierarchy. The organization layer is where you automate global identity and governance: invites bring people into the organization, users represent organization members, groups and roles describe membership and authorization structures, certificates and data retention represent security and compliance controls, and spend alerts and usage reporting help with operational finance. The project layer narrows those ideas to a project: users and groups can be attached to a project, service accounts and project API keys can be managed there, and project-level model, hosted tool, rate limit, data retention, certificate, and spend alert controls can be maintained without treating the entire organization as one unit.

Sources: src/resources/admin/organization/index.ts, src/resources/admin/organization/projects/index.ts

Client Setup and Request Pattern

A typical administrative script constructs the same OpenAI client used elsewhere in the SDK, but includes the adminAPIKey option. In tests, the client is constructed with an ordinary apiKey, an adminAPIKey, and a baseURL pointing to a local test server. Production code normally reads credentials from environment variables and leaves baseURL at the SDK default. Keeping the admin key separate makes scripts easier to audit because administrative authority is visible at construction time, and it avoids confusing ordinary user-facing model calls with organization-management operations.

Sources: tests/api-resources/admin/organization/usage.test.ts

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  adminAPIKey: process.env.OPENAI_ADMIN_KEY,
});
 
const usage = await client.admin.organization.usage.completions({
  start_time: 0,
  bucket_width: '1m',
  group_by: ['project_id'],
  project_ids: ['proj_123'],
});

Generated SDK calls return an awaitable API promise rather than a bare Response. The usage tests exercise three access modes: awaiting the promise for parsed data, calling asResponse() for the raw Response, and calling withResponse() for both parsed data and the raw response metadata. That pattern matters for admin tooling because operational jobs often need response headers, status codes, or request IDs for audit and troubleshooting, while dashboards and reports usually want the parsed data object. The same generated request shape appears in the admin usage tests for required-only and required-plus-optional parameter combinations.

Sources: tests/api-resources/admin/organization/usage.test.ts

Organization-Level Resource Reference

The organization index is the reference map for organization-scoped administration. AdminAPIKeys exports AdminAPIKey, create and delete response types, create and list parameter types, and AdminAPIKeysPage. AuditLogs exports list response and parameter types plus a paginated response page. Certificates exports certificate models and create, retrieve, update, list, activate, deactivate, and delete response or parameter types, including page types for list and state-change operations. DataRetention exports OrganizationDataRetention and update parameters. These names show that the SDK treats administration as typed REST resources with operation-specific inputs rather than as a single generic admin endpoint.

Sources: src/resources/admin/organization/index.ts

The same organization index covers identity and governance resources. Groups exports Group, create, update, list, delete response or parameter types, and GroupsPage. The nested group index further exposes group-specific Roles and Users, with types such as OrganizationGroupUser, RoleCreateResponse, RoleRetrieveParams, and OrganizationGroupUsersPage. Invites exports invite model, create/list/delete types, and InvitesPage. Users exports OrganizationUser, update/list/delete types, and OrganizationUsersPage. Roles exports role model, create/update/list/delete types, and RolesPage. Together, these exports support invitation flows, user lifecycle automation, group membership synchronization, and role assignment tooling.

Sources: src/resources/admin/organization/index.ts

For cost and activity reporting, the organization index exports SpendAlerts and Usage. Organization spend alerts include OrganizationSpendAlert, OrganizationSpendAlertDeleted, create/update/list parameter types, and OrganizationSpendAlertsPage. Usage exports response and parameter types for audio speeches, audio transcriptions, code interpreter sessions, completions, costs, embeddings, file search calls, images, moderations, vector stores, and web search calls. The usage test confirms callable methods for several of these categories and shows common optional filters such as api_key_ids, bucket_width, end_time, group_by, limit, models, page, project_ids, and user_ids. The required anchor in the tested calls is start_time.

Sources: src/resources/admin/organization/index.ts, tests/api-resources/admin/organization/usage.test.ts

Project-Level Resource Reference

Project administration starts from the Projects export, which includes Project, create/update/list parameter types, and ProjectsPage. Once a project exists, the project index exposes resource families for credentials, people, permissions, and controls. APIKeys exports ProjectAPIKey, retrieve/list/delete parameter types, delete response types, and ProjectAPIKeysPage. ServiceAccounts exports ProjectServiceAccount, create/retrieve/update/list/delete parameter types, create/delete response types, and ProjectServiceAccountsPage. These resources are the project-scoped credential surface: use them when an automation workflow should grant access to one project rather than to the entire organization.

Sources: src/resources/admin/organization/projects/index.ts

The project index also exposes membership and permission controls. Users exports ProjectUser plus create, retrieve, update, list, and delete parameter types and ProjectUsersPage. Groups exports ProjectGroup plus create, retrieve, list, and delete parameter types and ProjectGroupsPage. Roles exports create, retrieve, update, list, and delete parameter types for project role assignments. ModelPermissions exports ProjectModelPermissions, a deleted response type, and update parameters. HostedToolPermissions exports ProjectHostedToolPermissions and update parameters. Together these types indicate that a project can be governed through membership, role, model access, and hosted-tool access controls instead of relying only on organization-wide defaults.

Sources: src/resources/admin/organization/projects/index.ts

Operational limits and compliance controls are also project-scoped. RateLimits exports ProjectRateLimit, list and update parameter types, and ProjectRateLimitsPage. Certificates exports list, activate, and deactivate types with corresponding page types. DataRetention exports ProjectDataRetention and update parameters. SpendAlerts exports ProjectSpendAlert, ProjectSpendAlertDeleted, retrieve/create/update/list/delete parameter types, and ProjectSpendAlertsPage. These exports are useful when building internal project provisioning systems: one workflow can create or update the project, attach members and service accounts, configure model and hosted tool permissions, set rate limits, apply retention and certificate policy, and add spend alerts.

Sources: src/resources/admin/organization/projects/index.ts

Usage Reporting Details

The usage tests provide the clearest executable signal for admin reporting calls. Each tested method accepts an object with start_time, and the optional examples show how reporting can be narrowed or grouped. For audio speeches and audio transcriptions, optional fields include api_key_ids, bucket_width, end_time, group_by, limit, models, page, project_ids, and user_ids. Code interpreter session usage accepts bucket_width, end_time, group_by, limit, page, and project_ids. Completion usage includes the same reporting controls and also shows batch: true, which indicates reporting can distinguish batch-related usage when that option is supplied.

Sources: tests/api-resources/admin/organization/usage.test.ts

When building dashboards, treat these usage calls as paginated, filterable reports rather than simple counters. The exported usage response types cover multiple product areas, and the parameter names indicate common aggregation dimensions. A minimal script can request data starting at a timestamp, while a production report should specify a time window, choose a bucket width, filter to selected projects or users, and preserve pagination state with page. If the report is used for chargeback or compliance, prefer withResponse() so the job can log both parsed usage data and the raw HTTP response details returned by the SDK promise.

Sources: src/resources/admin/organization/index.ts, tests/api-resources/admin/organization/usage.test.ts

Implementation Notes and Next Steps

The admin resource files are generated from the OpenAPI specification by Stainless, matching the repository's general SDK architecture. That means the index files are public aggregation points, not hand-written business logic. For day-to-day application code, import OpenAI from the package, construct a client with adminAPIKey, and access resources through client.admin.organization rather than importing resource classes directly. Use the exported TypeScript types when building shared wrappers around administrative workflows, because those types are regenerated with the API surface and preserve operation-specific request and response shapes.

Sources: api.md, src/resources/admin/organization/index.ts, src/resources/admin/organization/projects/index.ts

As a practical next step, decide whether your workflow is organization-scoped or project-scoped before writing code. Organization-scoped scripts should start with admin API keys, audit logs, invites, users, groups, roles, certificates, data retention, spend alerts, and usage. Project-scoped provisioning should start with projects, then attach project users or groups, create service accounts or project API keys, configure model and hosted tool permissions, and set rate, certificate, retention, and spend controls. For exact method signatures beyond the exported type names summarized here, open api.md and the generated resource modules under the corresponding namespace.

Ask a question...