diff --git a/openapi.yaml b/openapi.yaml index e83d5966..39b08a0c 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3858,6 +3858,245 @@ paths: } ] } + /organization/admin_api_keys: + get: + summary: List organization API keys + operationId: admin-api-keys-list + description: Retrieve a paginated list of organization admin API keys. + parameters: + - in: query + name: after + required: false + schema: + type: string + nullable: true + description: Return keys with IDs that come after this ID in the pagination + order. + - in: query + name: order + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + description: Order results by creation time, ascending or descending. + - in: query + name: limit + required: false + schema: + type: integer + default: 20 + description: Maximum number of keys to return. + responses: + "200": + description: A list of organization API keys. + content: + application/json: + schema: + $ref: "#/components/schemas/ApiKeyList" + security: + - bearer_identity_edge: + - key.secret + - api.management.read + - basic_identity_edge: [] + x-oaiMeta: + name: List admin API keys + group: administration + returns: A list of admin API key objects. + examples: + request: + curl: > + curl + https://api.openai.com/v1/organization/admin_api_keys?after=key_abc&limit=20 + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.admin_api_key", + "id": "key_abc", + "name": "Main Admin Key", + "redacted_value": "sk-admin...def", + "created_at": 1711471533, + "owner": { + "type": "service_account", + "object": "organization.service_account", + "id": "sa_456", + "name": "My Service Account", + "created_at": 1711471533, + "role": "member" + } + } + ], + "first_id": "key_abc", + "last_id": "key_abc", + "has_more": false + } + post: + summary: Create an organization admin API key + operationId: admin-api-keys-create + description: Create a new admin-level API key for the organization. + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - name + properties: + name: + type: string + example: New Admin Key + responses: + "200": + description: The newly created admin API key. + content: + application/json: + schema: + $ref: "#/components/schemas/AdminApiKeyWithValue" + security: + - bearer_identity_edge: + - key.secret + - api.management.write + - basic_identity_edge: [] + x-oaiMeta: + name: Create admin API key + group: administration + returns: The created admin API key object. + examples: + request: + curl: > + curl -X POST https://api.openai.com/v1/organization/admin_api_keys + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "New Admin Key" + }' + response: | + { + "object": "organization.admin_api_key", + "id": "key_xyz", + "name": "New Admin Key", + "redacted_value": "sk-admin...xyz", + "created_at": 1711471533, + "owner": { + "type": "user", + "object": "organization.user", + "id": "user_123", + "name": "John Doe", + "created_at": 1711471533, + "role": "owner" + }, + "value": "sk-admin-1234abcd" + } + /organization/admin_api_keys/{key_id}: + get: + summary: Retrieve a single organization API key + operationId: admin-api-keys-get + description: Get details for a specific organization API key by its ID. + parameters: + - in: path + name: key_id + required: true + schema: + type: string + description: The ID of the API key. + responses: + "200": + description: Details of the requested API key. + content: + application/json: + schema: + $ref: "#/components/schemas/AdminApiKey" + security: + - bearer_identity_edge: + - key.secret + - api.management.read + - basic_identity_edge: [] + x-oaiMeta: + name: Retrieve admin API key + group: administration + returns: The requested admin API key object. + examples: + request: + curl: > + curl https://api.openai.com/v1/organization/admin_api_keys/key_abc + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.admin_api_key", + "id": "key_abc", + "name": "Main Admin Key", + "redacted_value": "sk-admin...xyz", + "created_at": 1711471533, + "owner": { + "type": "user", + "object": "organization.user", + "id": "user_123", + "name": "John Doe", + "created_at": 1711471533, + "role": "owner" + } + } + delete: + summary: Delete an organization admin API key + operationId: admin-api-keys-delete + description: Delete the specified admin API key. + parameters: + - in: path + name: key_id + required: true + schema: + type: string + description: The ID of the API key to be deleted. + responses: + "200": + description: Confirmation that the API key was deleted. + content: + application/json: + schema: + type: object + properties: + id: + type: string + example: key_abc + object: + type: string + example: organization.admin_api_key.deleted + deleted: + type: boolean + example: true + security: + - bearer_identity_edge: + - key.secret + - api.management.write + - basic_identity_edge: [] + x-oaiMeta: + name: Delete admin API key + group: administration + returns: A confirmation object indicating the key was deleted. + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/admin_api_keys/key_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "id": "key_abc", + "object": "organization.admin_api_key.deleted", + "deleted": true + } /organization/audit_logs: get: summary: List user actions and configuration changes within this organization. @@ -4183,26 +4422,25 @@ paths: \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" - response: - content: | - { - "object": "list", - "data": [ - { - "object": "organization.invite", - "id": "invite-abc", - "email": "user@example.com", - "role": "owner", - "status": "accepted", - "invited_at": 1711471533, - "expires_at": 1711471533, - "accepted_at": 1711471533 - } - ], - "first_id": "invite-abc", - "last_id": "invite-abc", - "has_more": false - } + response: | + { + "object": "list", + "data": [ + { + "object": "organization.invite", + "id": "invite-abc", + "email": "user@example.com", + "role": "owner", + "status": "accepted", + "invited_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": 1711471533 + } + ], + "first_id": "invite-abc", + "last_id": "invite-abc", + "has_more": false + } post: summary: Create an invite for a user to the organization. The invite must be accepted by the user before they have access to the organization. @@ -4234,20 +4472,40 @@ paths: -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ - "email": "user@example.com", - "role": "owner" + "email": "anotheruser@example.com", + "role": "reader", + "projects": [ + { + "id": "project-xyz", + "role": "member" + }, + { + "id": "project-abc", + "role": "owner" + } + ] }' - response: - content: | - { - "object": "organization.invite", - "id": "invite-abc", - "email": "user@example.com", - "role": "owner", - "invited_at": 1711471533, - "expires_at": 1711471533, - "accepted_at": null - } + response: | + { + "object": "organization.invite", + "id": "invite-def", + "email": "anotheruser@example.com", + "role": "reader", + "status": "pending", + "invited_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": null, + "projects": [ + { + "id": "project-xyz", + "role": "member" + }, + { + "id": "project-abc", + "role": "owner" + } + ] + } /organization/invites/{invite_id}: get: summary: Retrieves an invite. @@ -11087,6 +11345,72 @@ components: format: binary required: - data + AdminApiKey: + type: object + properties: + object: + type: string + example: organization.admin_api_key + id: + type: string + example: key_abc + name: + type: string + example: Administration Key + redacted_value: + type: string + example: sk-admin...def + created_at: + type: integer + format: int64 + example: 1711471533 + owner: + type: object + properties: + type: + type: string + example: service_account + id: + type: string + example: sa_456 + name: + type: string + example: My Service Account + created_at: + type: integer + format: int64 + example: 1711471533 + role: + type: string + example: member + AdminApiKeyWithValue: + AdminApiKeyWithValue: + allOf: + - $ref: "#/components/schemas/AdminApiKey" + - type: object + properties: + value: + type: string + example: sk-admin-1234abcd + ApiKeyList: + type: object + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/AdminApiKey" + has_more: + type: boolean + example: false + first_id: + type: string + example: key_abc + last_id: + type: string + example: key_xyz AssistantObject: type: object title: Assistant @@ -17133,6 +17457,22 @@ components: accepted_at: type: integer description: The Unix timestamp (in seconds) of when the invite was accepted. + projects: + type: array + description: The projects that were granted membership upon acceptance of the + invite. + items: + type: object + properties: + id: + type: string + description: Project's public ID + role: + type: string + enum: + - member + - owner + description: Project membership role required: - object - id @@ -17152,7 +17492,13 @@ components: "status": "accepted", "invited_at": 1711471533, "expires_at": 1711471533, - "accepted_at": 1711471533 + "accepted_at": 1711471533, + "projects": [ + { + "id": "project-xyz", + "role": "member" + } + ] } InviteDeleteResponse: type: object @@ -17207,6 +17553,27 @@ components: - reader - owner description: "`owner` or `reader`" + projects: + type: array + description: An array of projects to which membership is granted at the same + time the org invite is accepted. If omitted, the user will be + invited to the default project for compatibility with legacy + behavior. + items: + type: object + properties: + id: + type: string + description: Project's public ID + role: + type: string + enum: + - member + - owner + description: Project membership role + required: + - id + - role required: - email - role @@ -24532,10 +24899,10 @@ x-oaiMeta: - id: administration title: Administration description: > - Programmatically manage your organization. + Programmatically manage your organization. - The Audit Logs endpoint provides a log of all actions taken in - the organization for security and monitoring purposes. + The Audit Logs endpoint provides a log of all actions taken in the + organization for security and monitoring purposes. To access these endpoints please generate an Admin API Key through the [API Platform Organization overview](/organization/admin-keys). Admin @@ -24544,10 +24911,38 @@ x-oaiMeta: For best practices on setting up your organization, please refer to this [guide](/docs/guides/production-best-practices#setting-up-your-organization) navigationGroup: administration + - id: admin-api-keys + title: Admin API Keys + description: > + The **Usage API** provides detailed insights into your activity across + the OpenAI API. It also includes a separate [Costs + endpoint](/docs/api-reference/usage/costs), which offers visibility into + your spend, breaking down consumption by invoice line items and project + IDs. + + While the Usage API delivers granular usage data, it may not always + reconcile perfectly with the Costs due to minor differences in how usage + and spend are recorded. For financial purposes, we recommend using the + [Costs endpoint](/docs/api-reference/usage/costs) or the [Costs + tab](/settings/organization/usage) in the Usage Dashboard, which will + reconcile back to your billing invoice. + navigationGroup: administration + sections: + - type: endpoint + key: admin-api-keys-list + path: list + - type: endpoint + key: admin-api-keys-create + path: create + - type: endpoint + key: admin-api-keys-get + path: listget + - type: endpoint + key: admin-api-keys-delete + path: delete - id: invite title: Invites - description: Invite and manage invitations for an organization. Invited users - are automatically added to the Default project. + description: Invite and manage invitations for an organization. navigationGroup: administration sections: - type: endpoint @@ -24567,9 +24962,8 @@ x-oaiMeta: path: object - id: users title: Users - description: > - Manage users and their role in an organization. Users will be - automatically added to the Default project. + description: | + Manage users and their role in an organization. navigationGroup: administration sections: - type: endpoint @@ -24591,9 +24985,9 @@ x-oaiMeta: title: Projects description: > Manage the projects within an orgnanization includes creation, updating, - and archiving or projects. + and archiving or projects. - The Default project cannot be modified or archived. + The Default project cannot be archived. navigationGroup: administration sections: - type: endpoint @@ -24618,10 +25012,7 @@ x-oaiMeta: title: Project users description: > Manage users within a project, including adding, updating roles, and - removing users. - - Users cannot be removed from the Default project, unless they are being - removed from the organization. + removing users. navigationGroup: administration sections: - type: endpoint @@ -24646,10 +25037,10 @@ x-oaiMeta: title: Project service accounts description: > Manage service accounts within a project. A service account is a bot - user that is not associated with a user. + user that is not associated with a user. If a user leaves an organization, their keys and membership in projects - will no longer work. Service accounts + will no longer work. Service accounts do not have this limitation. However, service accounts can also be deleted from a project. @@ -24674,7 +25065,7 @@ x-oaiMeta: title: Project API keys description: > Manage API keys for a given project. Supports listing and deleting keys - for users. + for users. This API does not allow issuing keys for users, as users need to authorize themselves to generate keys. @@ -24711,11 +25102,10 @@ x-oaiMeta: - id: audit-logs title: Audit logs description: > - Logs of user actions and configuration changes within this - organization. + Logs of user actions and configuration changes within this organization. To log events, you must activate logging in the [Organization - Settings](/settings/organization/general). + Settings](/settings/organization/general). Once activated, for security reasons, logging cannot be deactivated. navigationGroup: administration