Application scopes

Every Developer Console application corresponds to an OAuth client that is responsible for handling Foundry authorization. During OAuth authorization, third-party applications are granted tokens that are restricted by scopes to only permit certain operations and resources. The scopes applied to a given token depend on the following:

1. The permissions of the specific application user (for authorization code grants) or service user (for client credentials grants) in Foundry. Review the authentication grant types documentation for further details.
2. The maximum scope set for the given Developer Console application. Maximum scopes may also be set on legacy OAuth clients that do not have an associated Developer Console application.
3. The scope requested by the third-party application as part of a token request (also known as "authorization time"). Token requests that do not request a scope will default to allowing all of the user’s permissions that are allowed by the OAuth client’s maximum scope; no additional restrictions will be applied at authorization time.

Configure an application's maximum scope

You can control the maximum scope that an application’s OAuth client is allowed to request using the Resources panel in Developer Console. This configuration provides all users the ability to limit the actions an application may take or the data an application may read from Foundry.

From the Resources tab, choose to configure Ontology SDK resources or Platform SDK resources.

Ontology SDK resources

If your application should interact with the Ontology (typically using the OSDK), use the Ontology SDK resources tab to add object types, interfaces, actions, and functions to the list of application resources. Adding Ontology resources will change a Developer Console application in two ways:

1. The maximum scope will allow access to the listed resources.
2. Any new SDKs generated for the application will include the listed resources.

Platform SDK resources

If your application should interact with platform APIs (typically using platform SDKs, use the Platform SDK resources tab to add Foundry projects and operational API namespaces to the application scope.

• Project access: Choose the Foundry projects that an application may interact with. Scoped applications may only read or write to resources inside one of these projects. If an application must interact with a Foundry resource that is not inside a project, consider using an unscoped application.
• Client-allowed operations: Choose the methods an application may use to interact with the selected project resources. Operations are grouped by API namespace which correspond to the path of the endpoint; for example, the /admin/ API namespace includes all endpoints with the path /api/{the api version number}/admin/. More details on API namespaces can be found in the API documentation.

API-level security for client-allowed operations

As of Spring 2025, new Developer Console applications enforce API-level security for scoped applications, ensuring that every endpoint called by these applications must be explicitly added to the client-allowed operations list in the Platform SDK resources panel. Unscoped applications are not affected by these changes and will continue to be able to call endpoints to which the user has the necessary permissions. Note that unscoped applications should generally only be used for programmatic, platform-wide workflows.

Foundry provides a migration path to upgrade your existing applications to use this new security model. Review the section below for more details.

Unscoped applications

Unlike scoped applications, unscoped applications only consider the application user's permissions when determining access. We recommend only using unscoped applications for cases where defining necessary resources or operation access in advance is impossible or impractical. For example:

• Tools that must interact with a set of Foundry resources that cannot be defined at deployment time (for example, resources in projects that have not yet been created).
• Tools that must interact with administrative primitives that do not exist within a project (for example, spaces, organizations, providers, and enrollments).
• Working with endpoints that are not yet officially released in the platform API.

Generally, most applications that have a user interface or use authorization code grants should use a scope to provide strict access guarantees that are not subject to individual user permissions.

Create an unscoped application

To create an unscoped application, select No, I will not use an Ontology SDK when setting up a new application in Developer Console.

The created unscoped application will not support some Developer Console capabilities, including SDK generation, metrics, and subdomain hosting. However, support for unscoped applications may improve in the future.

Migrate to API security

As explained above, as of Spring 2025, new Developer Console applications enforce API-level security to ensure that every endpoint called by a scoped third-party application must be individually added to the list of client-allowed operations.

Any new or migrated applications will now restrict two types of application access that were previously allowed: underlying service endpoints and implicit operation grants.

No access to underlying service endpoints

Scoped applications are not allowed to call underlying service APIs, which are endpoints that are not explicitly documented or exposed to users.

The scopes used by Developer Console application clients now contain the prefix use-; for example: api:use-ontologies-read instead of api:ontologies-read. These new permissions allow you to only call Foundry platform APIs and are blocked from hitting underlying service endpoints.

An important exception to API-security is a set of adminstrative endpoints designed to always be accessible to users for the purpose of identification, authorization, or access debugging. These endpoints are not designed for broad public usage and are thefore not included in the public Foundry API documentation or the Platform SDK resources panel. Such endpoints include the following: * OAuth2: /multipass/api/oauth2/... * User information: multipass/api/me/... * Resource access information: /multipass/api/authz/... * Token TTL: /multipass/api/token/... * Organizations: /multipass/api/organizations/...

These endpoints may always be called by scoped applications.

No implicit operation grants

With the addition of advanced API-level security, each API namespace is strictly isolated. Prior to these changes, granting an API namespace scope gave an application access to endpoints in that namespace as well as any dependent endpoints within other namespaces. The new, more secure API scopes (with the prefix use-) provide access only to the directly granted API namespaces. This ensures that application administrators can firmly control the actions applications may take within their organization.

For example, a legacy application that is granted /ontologies/ API namespace permissions (api:use-ontologies-read) may query the basic user identity information with the /api/v2/admin/users/getCurrent endpoint in the /admin/ namespace, since several Ontology endpoints require these operations for authentication purposes. Once migrated to our improved security protocols, if an application is only granted the api:use-ontologies-read and api:use-ontologies-write scopes, the application will be prevented from accessing this user information and receive an ApiUsageDenied error.

By default, all Developer Console applications created after the security update or migrated to use the advanced API-level protection will be configured with the api:use-ontologies-read and api:use-ontologies-write scopes.

Migration steps

Follow the steps below to migrate your Developer Console application to use advanced API security:

1. Navigate to the Platform SDK resources tab and select Migrate.

2. Follow the instructions in the pop-up module to update your application code. If you are using the TypeScript SDK, change the requested operation scopes to use new scopes that respect the upgraded security model. To prevent temporary breaks, do not remove any of the original operation scopes while adding the new scopes.

3. Once the application is successfully migrated, you can remove the original, outdated scopes from your application code.

.