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 are the intersection of 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 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.
3. The maximum scope set for the given Developer Console application or Standalone OAuth client.

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 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 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

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 panel. Unscoped applications are not affected by these changes and will continue to be able to call endpoints that the user has the necessary permissions to access. Note that unscoped applications should generally only be used for programmatic, platform-wide workflows.

Unscoped applications

Unscoped applications only consider the application user's permissions when determining access, rather than restricting access to a predefined set of resources.

By default, custom applications are scoped to encourage stricter security guarantees. Use unscoped applications in the following situations:

• Resources cannot be defined at deployment time (for example, projects that do not yet exist).
• Your application must access administrative primitives outside of projects (for example, spaces, organizations, or enrollments).
• You need to work with endpoints not yet released in the platform API.

Change application scope

You can switch between scoped and unscoped from the OAuth & scopes page under Application scope.

To switch to an unscoped application, select the option and type I confirm to acknowledge. Note that switching to unscoped removes your current project access and operation scope configuration.

To revert to a scoped application, select the option and complete the wizard to configure project access and platform API operations. Your application may break if it uses resources not added during this configuration.

Standalone OAuth clients [Legacy]

Standalone OAuth clients are a legacy, lightweight alternative to custom applications. Beyond the auth client itself, standalone OAuth clients do not provide application building capabilities such as scopes, metrics, or SDK generation.

Unscoped applications replace standalone OAuth clients by providing equivalent access flexibility inside a fully featured custom application.

Migration steps to convert standalone OAuth clients into unscoped custom applications will be available in a future release.

Migrate to API security

As explained above, Developer Console applications created after June 1, 2025 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. Follow the migration steps below for applications created prior to June 1, 2025.

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 administrative 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 therefore 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.

Scope prefixes

Foundry uses two scope prefixes for API permissions:

When choosing which scope to use:

• Scoped applications should use api:use-* scopes (for example, api:use-ontologies-read).
• Standalone OAuth clients should use api:* scopes (for example, api:ontologies-read) since they call Foundry directly, as described above. Note: standalone OAuth clients are a legacy primitive being replaced by unscoped applications.
• Unscoped applications should use api:use-* scopes unless they are querying underlying Foundry service endpoints.

This pattern applies across all API namespaces, including admin, ontologies, datasets, and others.