Skip to main content
Managing projects in the API platform
Updated this week

Projects aim to provide customers the ability to organize their work. Organizations can manage access and limits, provision service accounts (through the UI), and track usage against a constrained scope within a project (e.g. models, capabilities, threads, assistants, fine tuning, storage, etc.). Usage activity can be broken down by project, and users can view billing and set cost restrictions per project.

Organization owners can view all of their Active and Archived projects in the Projects page. Learn more about user roles and permissions in the API Platform.

Who can create a project?

Only organization owners can create a project. Please refer to roles and permissions for more information.

To switch between organizations, hover over your organization’s name on the top-left of the page and select the organization from the list:

For those organizations that are on a consolidated billing plan, sub-orgs are identified separately. Projects cannot be created within sub-orgs.

How do projects work?

Every organization includes a “Default project,” which cannot be deleted. You can configure the rate limits, virtual model permissions, and spend limits (as of November 2024). It inherits the full configuration of the organization, so you cannot directly add members or service accounts to it.

How do I create a project?

First, hover on the project name on the left-corner of the page and select Create project.

Provide a name, description, and website for your project and then select Create.

How do I add users to a project?

Newly added organization members are not automatically added to the “Default project”. New members can be invited to the project either when they are invited to the organization (by enabling the "Invite to default project" checkbox) or after the member has accepted the organization invitation.

Users invited via the Admin API follow the rules outlined by the /organization/invites endpoint.

Organization owners are automatically added as owners to new projects created within an organization.

What are the different user roles within organizations and projects, and what permissions do they entail?

Whereas Organizations have ‘owner’ and ‘reader’ roles, projects have ‘owner’ and ‘member’ roles. Project members are analogous to organization readers. Please refer to the table below for a more detailed description of what permissions accompany each user role.

Role

Scope

Description

Owner

Organization

Can create/view all projects, all users, all API keys. Has the ability to monitor across all projects within the organization with the Projects page. Able to set billing controls. Can grant permissions to view usage information for others in the org. Can archive projects.

Reader

Organization

Can perform inference, use resources, and create keys. Can be added to projects.

Cannot create projects and manage users.

Owner

Project

Can add other users to the project and rename the project, as well as all the abilities of a Member. Can archive the project.

Member

Project

Can perform inference, use resources, and create keys at the project level.

If I’m not an Owner in the organization, what do I have access to?

Users that are not Owners in the organization can only see projects that they are members of. Only the organization owner can see all projects, members, and API keys at the project level, and have access to the Projects page.

  • Only the members of a project (and organization owners) can see the fine tuned models that have been created within that project, the threads from any Assistants created, or any files that have been added.

  • Members of a project can see who all the other members of that project are and their roles (i.e. Owner or Member).

How do I update a user’s project role or remove a user from a project?

Only the Owner of a project can update a user’s project role or remove a user from a project. Please refer to roles and permissions for more information.

To update a user in a project, go to your organization settings, select the project, and click on Members. You have the option to set each member’s role as a Member or Owner. You can also select Remove to remove the user from the project.

What is a service account, and how does it differ from a regular user account?

A service account acts as a pseudo-user designed for system access, distinct from individual user accounts. Only organization and project owners can create service accounts.

Service accounts are only scoped to projects.

Add a member to a project

If you click the + Add member button you will see a list of users in your organization with the role Reader. If you want to add the user who is not currently within your organization, you'd need to add them to the organization first (you can keep the 'Add to Default Project" checkbox unchecked if you don't want to give these users wider access). This list will not include service accounts. During this step you can choose if their role is either Owner or Member:

When you add a team member, you must assign them either the Member or Owner role. Project members can make API requests that read or modify data, whereas project owners can also modify project settings and manage project members. Please refer to roles and permissions for more information.

How to create a service account for a project

First navigate to the project you want to create a service account for by choosing from the dropdown found in the navigation bar:

Then, go to your organization settings -> Project -> Members -> click on + Service account:

Service accounts created at the project level are unique to the project and cannot be used outside of the project they are created in.

Naming the service account

Regardless of whether you create the service account at the organization level or create one unique to a project, when you create a service account you can create a unique service account ID consisting of letters, numbers, and hyphens to easily identify the service account.

Save the service account API key

After selecting the Create button, an API key is immediately created for the service account and the secret key will be displayed. Save this secret key somewhere safe and secure. For security reasons, you won't be able to view it again through your OpenAI account. If you lose this secret key, then you will need to generate a new one.

The service account API key permissions are defaulted to read and write all of the project’s API resources. These permissions can be updated in your project’s API Keys settings.

Service accounts are listed alongside project members in your project’s member settings page. Please refer here to learn more about updating or removing a service account’s access in your project’s member settings page.

All service accounts across both projects and organizations will be displayed alongside your human users in the organization level members page.

Service accounts are managed like regular accounts. From the Organization -> Members menu you can Remove a service account or update the role:

What is the difference between a project API key and a Service Account?

All project API keys are tied to individual user accounts. If the user leaves the project of organization, the API key becomes disabled. To maintain continuity with production/system access, we recommend using Service account API keys because service account API keys can be more easily managed by organization and project owners.

How do I manage API keys within my organization's projects?

You can create and manage API keys for each project on that project’s settings page. In your organization settings, select the project, and click on API Keys.

To create a new secret key, select + Create new secret key. You can also select the Edit icon next to a secret key to edit its permissions.

You can set permissions for each of your API keys when you create a new secret key or by editing an existing key.

Three levels of permissions are available: All, Restricted, and Read Only.

  • All ― Full permissions are set for the secret key. This is the default setting.​

  • Restricted ― Enables the user to set None, Read, and Write permissions for each endpoint.

    • For example, you create an API key that specifically does not have permission to Read or Write to the /v1/assistants endpoint:

  • Read Only ― Read permissions are set for all endpoints.

How is access managed for users belonging to multiple projects or organizations?

Users can be members of as many projects as are needed. Within a project, users can generate a personal API key that is scoped and limited to accessing that project and its resources.

How do organization limits affect my project limits?

Limits can be set across all projects and will be individually enforced. However, if the organization limit is reached before the project limit, the projects will also be rate limited.

  • If project limits sum to equal org limit, org limit will be reached if and only if ALL project limits are reached. No individual project reaching its limit can limit another project.

  • If project limits sum to greater than org limit, org limit will be reached when sum of project usage equals org limit. The highest using project CAN limit another project.

Example:

Project A: $100 limit // Project B: $100 limit // Project C: $100 limit

Scenario 1: $400 Org limit

Scenario 2: $300 Org limit

Scenario 3: $200 Org limit

Limits of A+B+C < Org limit

  • Project limits can be reached

  • Org billing limit will never be reached

  • Usage at A, B, or C is NOT interdependent

Limits of A+B+C = Org limit

  • Project limits can be reached

  • Org billing limit may be reached

  • Usage at A, B, or C is NOT interdependent

Limits of A+B+C > Org limit

  • Project limits may be reached

  • Org billing limit may be reached

  • Usage at A, B, or C is interdependent

How do I set and manage rate limits for my organization's projects?

Only the Owner of an organization can set and manage billing restrictions. Please refer to roles and permissions for more information.

In your organization settings, click on the project you want to update and select Limits. You can update your Model Usage on this page.

Model usage allows you to configure which models can be used by the project, and rate limits can be set for each model as needed.

How do I set and manage billing restrictions for my organization's projects?

Only the Owner of an organization can set and manage billing restrictions. Please refer to roles and permissions for more information. Any limits you set at a per project level will always be less than or equal to the limits set at the organization level. To change the limits at the organization level, in your organization settings, click on Limits, and scroll down to Usage limits.

To set your project limits, in your organization settings, click on the project you want to update and select Limits. You can update your Monthly budget, Notification threshold, and Model Usage.

The Monthly budget allows you to set a hard limit for the project’s budget. If the project's usage exceeds this amount in a given calendar month (UTC), all subsequent API requests are blocked.

To receive billing alerts for a project’s usage, you can set a budget limit under Notification threshold. If the project's usage exceeds this amount, all project and organization owners will be sent an email.

Please note that the organization owner(s) and project owner(s) will always receive these messages and this cannot be customized. In all cases, project-level limits must be lower than your organization’s limits.

How do I delete or archive a project?

Projects can be archived through either the new project listing page or on the settings of an individual project. Once a project is archived it cannot be restored. When proceeding with an archive, you will be prompted to enter the project’s name to proceed forward.

You can view a list of all archived projects through the “Archived” tab on the same project listing page.

Deleting projects is not possible, we maintain a history of all projects to ensure continuity with usage and billing tracking.

Is there a limit to the number of projects I can have in my organization?

Organizations can create up to 1000 projects.

Can resources be shared across projects?

Project resources (such as files, assistants, storage, or threads) are scoped to the project and cannot be accessed from non-admin members outside of the project. Furthermore, resources cannot be moved between projects.

The one exception is that fine tunes in the "Default project" can be accessed from other projects.

What is the file storage quota per project?

OpenAI currently support a file storage quota of 100 GB of files per project.

If this quota is breached, you will see the following error:

You have exceeded your file storage quota. Organizations are limited to 100 GB of files. Please reduce the file size or contact support.

We recommend you delete unused files stored on your account. For reference, you can view and list files with the API.

I'm a project owner, why can't I see the Usage Dashboard for my project?

A projects Usage Dashboard visibility is not related to the role of a user within a project. Instead, it is determined by your role within the organization and the settings at https://platform.openai.com/settings/organization/data-controls/visibility

If you're unable to see a Usage Dashboard, this setting is likely set to "Visible to organization owners".

Did this answer your question?