Skip to main content

Issue a project-scoped API key

Enterprise Tier

An API key is the credential an application presents when it calls a gateway. Keys are created in the context of a project, so a key belongs to one project and resolves to that project on every endpoint that serves it.

Because keys are project-scoped, they are part of what keeps projects isolated from one another: every request resolves to its project from its key, never from the hostname it was sent to, so a key reaches only the models its own project has been granted, even on a hostname that serves several projects.

Persona: Platform operator or project administrator working in the Admin Console.

Estimated time: 5 minutes per key.

Outcomes​

By the end of this guide:

  • An API key exists that is scoped to a single project.
  • The key's scope is understood: it works on every endpoint serving its project, and only for that project.
  • The one-time nature of the key value is understood, so it is captured securely at creation.

Prerequisites​

  • Membership of the project, with permission to create keys.
  • At least one data plane is labelled with the project, so the key has an endpoint to call. See Serve a project from a data plane.

Step 1: select the project​

  1. Use the project switcher at the top of the application to select the project the key is for, for example bedrock-team.
  2. Confirm the application has re-scoped to that project before creating the key.

Everything done in the application, including key creation, applies to the currently selected project. Selecting the wrong project produces a key for the wrong project, which the intended project's endpoints refuse.

Step 2: create the API key​

  1. Open API Keys and select Add API Key.
  2. Name the key so its purpose is recognizable later, then create it.
  3. Copy the key value immediately. It is shown once, so it must be captured at this point and stored securely.

Step 3: understand the key's scope​

The key is bound to the project it was created in.

  • It works on every endpoint the Developer Console lists for the project: every hostname declared by every data plane labelled with the project. One key needs no per-endpoint setup.
  • Sent to a hostname whose data plane does not serve its project, it is refused with 403 and category hostname_not_selected.
  • It can call only the models granted to the project, and a request for any other model is refused. On a data plane on 0.7.0 or later that serves several projects on one hostname, a model that another project there serves is refused with 400 model_not_found, the same answer an unknown model gets, so the key learns nothing about the other project.

This scoping is automatic and needs no extra configuration. The same isolation applies to MCP: a profile reached with a key from another project is refused, and a key lists and reaches only its own project's MCP servers and profiles, also on a shared hostname. Organization-wide key practices, including rotation and revocation, are covered in Onboard developers and issue keys.

Where to go next

Grant MCP servers and profiles to a project

Expose tools through the project, reached with this project key.

Onboard developers and issue keys

The organization-wide view of users, roles, and key lifecycle.

Serve a project from a data plane

The endpoints this key works on, and which address developers see.