Application restrictions（应用限制）

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 scope of a given token is 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 maximum restrictions set for the given Developer Console application. An application can also be left unrestricted.
3. The operation 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 restrictions. No additional limits will be applied at authorization time.

:::callout{theme="neutral" title="Restrictions versus scopes"} Restrictions are configured in Developer Console and define the maximum scope an application can ever have. A token scope, determined at runtime, is the intersection of the application's restrictions, the logged in user or service user's access permissions, and the operation scope the application requests in code. :::

:::callout{theme="warning"} All tokens must have scopes restricted either at the OAuth client level (through application restrictions) or at authorization time (through the token request). Attempting to request a token with no scope restrictions will generate a token with no permissions. :::

Configure application restrictions

An application can be set as restricted or unrestricted.

1. Restricted applications are created by default. This means that Developer Console controls the resources and operations an application may use in Foundry.
2. Unrestricted applications have no maximum allowed resource or operation controls. Only the user permissions and the operations requested at authorization time are used to determine access.

You can switch between a restricted and unrestricted application from the OAuth & restrictions page under Application restrictions. Note that switching to an unrestricted application removes your current project access and operation restriction configuration.

When switching from an unrestricted to a restricted application, you will need to configure project access and platform API operations. Your application may break if it uses resources not added during this configuration.

Restricted applications

Restricted applications control the maximum resources and operations that an application's OAuth client is allowed to request. For example, consider a user who has permission to read a certain Foundry dataset and is querying that dataset via a restricted, third-party application that requests api:use-datasets-read. The user will not have access until two things are added to the application's restrictions:

1. The project containing that dataset is added to the application's resource restrictions
2. api:use-datasets-read is added to the application's operation restrictions.

Restricted applications provide increased legibility up front by defining, at build time, everything an application may do on behalf of its user. This minimizes cases of privilege escalation where application code uses the access of its user to take an action that the application builder did not have access to. Restrictions also serve as a guaranteed limit on the data Foundry can send to a specific device or system. For example, restrictions can guarantee that an application displayed in a control room will never show sensitive content, regardless of the user logged into the application.

Resource restrictions

Resource restrictions define which Foundry resources an application can access. Configure resource restrictions in the following locations in Developer Console, accessible from the left navigation panel.

• Ontology SDK tab: If your application interacts with the Ontology (typically using the OSDK), use this 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:
• The application's resource restrictions will allow access to the listed resources.
• Any new SDKs generated for the application will include the listed resources.

• Platform SDK tab: If your application interacts with platform APIs (typically using platform SDKs), use this tab to add Foundry projects to the resource restrictions. Restricted applications may only read or write to resources inside these projects. If an application must interact with a Foundry resource that is not inside a project, consider using an unrestricted application.

Operation restrictions

Operation restrictions define which API operations an application can perform. Unlike resource restrictions, you can only configure operation restrictions in the Platform SDK tab.

From here, add allowed operations via API namespaces. Choose the methods an application may use to interact with the selected project resources. Operations are grouped by API namespace, which corresponds to the path of the endpoint; for example, the /admin/ API namespace includes all endpoints with the path /api/{version}/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 restricted applications, ensuring that every endpoint called by these applications must be explicitly added to the operation restrictions list in the Platform SDK panel. Unrestricted 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 unrestricted applications should generally only be used for programmatic, platform-wide workflows.

Unrestricted applications

Unrestricted 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 restricted to encourage stricter security guarantees. Use unrestricted 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.

:::callout{theme="warning"} Unrestricted applications can interact with any resource the application user has access to. Only use unrestricted applications with trusted code. :::

Request a scope at authorization time

In addition to the restrictions configured in Developer Console, a third-party application can also request an operation scope as part of authentication. As described above, the requested scope is intersected with the application's restrictions and the user's underlying permissions when determining access. Note that a Foundry third-party application can only request operations at authorization time. Resource access is determined only by the application's resource restrictions and user permissions and does not require a request.

Foundry endpoints document their required scopes in the API documentation. The following example shows a TypeScript OAuth client scope request to read ontology data and Foundry datasets:

const scopes = ["api:use-ontologies-read", "api:use-datasets-read"];

export const auth: PublicOauthClient = createPublicOauthClient(
    clientId,
    foundryUrl,
    redirectUrl,
    { scopes },
);

/**
 * Initialize the client to interact with the Ontology and Platform SDKs
 */
export const client: Client = createClient(foundryUrl, ontologyRid, auth);

An empty ([]) requested operation scope will default to the application's operation restrictions. Unrestricted applications have no maximum allowed restrictions and behave differently depending on the type of authentication grant requested:

1. Client Credentials grant: A scope request is not required. An application with no requested scope will be granted all operations that the service user has access to.
2. Authorization Code grant: Applications must request a scope. During Authorization Code flow, a human user consents to a set of requested operations. Application builders must therefore define what operations the application needs. This helps minimize attack vectors related to privilege escalation.

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 restricted third-party application must be individually added to the list of client-allowed operations. Follow the migration steps below for applications created before 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

Restricted 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 only allow you to call Foundry platform APIs and are blocked from calling 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 restricted 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 the 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 will 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.

1. Follow the instructions in the dialog 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.

1. 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:

Scope pattern	Example	Use case
api:use-*-read/write	api:use-ontologies-read	New restricted Developer Console applications. Allows public API calls only.
api:*-read/write	api:ontologies-read	Standalone OAuth client and certain unrestricted applications. Allows public API calls and internal service endpoints.

When choosing which scope to use:

• Restricted 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 unrestricted applications.
• Unrestricted 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, streams, and others.

Standalone OAuth clients [Legacy]

:::callout{theme="neutral"} Standalone OAuth clients can no longer be created from Developer Console. Instead, we recommend creating unrestricted Developer Console applications. :::

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 restrictions, metrics, or SDK generation.

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

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

See also

• Permissions: Learn more about user and application permission types as well as resource access restrictions.
• OAuth clients: Learn how to create and manage OAuth clients.

---

中文翻译

应用限制

每个开发者控制台(Developer Console)应用都对应一个OAuth客户端，负责处理Foundry的授权。在OAuth授权过程中，第三方应用获得的令牌会受到作用域(scopes)的限制，仅允许执行特定操作和访问特定资源。给定令牌的作用域是以下三者的交集：

1. 特定应用用户（授权码授权类型）或服务用户（客户端凭证授权类型）在Foundry中的权限。详情请参阅认证授权类型文档。
2. 为给定开发者控制台(Developer Console)应用设置的最大限制(restrictions)。应用也可以设置为无限制。
3. 第三方应用在令牌请求中请求的操作作用域，也称为"授权时(authorization time)"。未请求作用域的令牌请求将默认允许OAuth客户端限制所允许的所有用户权限，授权时不会施加额外限制。

:::callout{theme="neutral" title="限制与作用域"} 限制(Restrictions)在开发者控制台(Developer Console)中配置，定义了应用可能拥有的最大作用域。令牌作用域(Token scope)在运行时确定，是应用限制、登录用户或服务用户的访问权限以及应用在代码中请求的操作作用域三者的交集。 :::

:::callout{theme="warning"} 所有令牌的作用域必须在OAuth客户端级别（通过应用限制）或授权时（通过令牌请求）进行限制。尝试请求无作用域限制的令牌将生成一个没有任何权限的令牌。 :::

配置应用限制

应用可以设置为受限或无限制。

1. 受限应用(Restricted applications)默认创建。这意味着开发者控制台(Developer Console)控制应用在Foundry中可使用的资源和操作。
2. 无限制应用(Unrestricted applications)没有最大允许资源或操作控制。仅使用用户权限和授权时请求的操作来确定访问权限。

您可以在应用限制(Application restrictions)下的OAuth与限制(OAuth & restrictions)页面切换受限和无限制应用。请注意，切换到无限制应用将移除您当前的项目访问和操作限制配置。

当从无限制应用切换到受限应用时，您需要配置项目访问和平台API操作。如果您的应用使用了未在此配置中添加的资源，可能会发生故障。

受限应用

受限应用控制应用的OAuth客户端允许请求的最大资源和操作。例如，考虑一个有权读取某个Foundry数据集的用户，该用户通过一个受限的第三方应用查询该数据集，该应用请求了api:use-datasets-read。只有在应用限制中添加以下两项后，用户才能访问：

1. 包含该数据集的项目被添加到应用的资源限制中
2. api:use-datasets-read被添加到应用的操作限制中

受限应用通过在构建时定义应用可能代表用户执行的所有操作，提高了前期的可读性。这最大限度地减少了权限提升的情况，即应用代码利用用户的访问权限执行应用构建者本无权执行的操作。限制还作为Foundry可以向特定设备或系统发送数据的保证上限。例如，限制可以保证在控制室中显示的应用永远不会显示敏感内容，无论登录该应用的用户是谁。

资源限制

资源限制定义了应用可以访问哪些Foundry资源。在开发者控制台(Developer Console)中，可通过左侧导航面板访问以下位置来配置资源限制。

• 本体SDK选项卡(Ontology SDK tab)： 如果您的应用与本体(Ontology)交互（通常使用OSDK），请使用此选项卡将对象类型、接口、操作和函数添加到应用资源列表中。添加本体资源将以两种方式改变开发者控制台(Developer Console)应用：
• 应用的资源限制将允许访问列出的资源。
• 为应用生成的任何新SDK将包含列出的资源。

• 平台SDK选项卡(Platform SDK tab)： 如果您的应用与平台API交互（通常使用平台SDK），请使用此选项卡将Foundry项目添加到资源限制中。受限应用只能读取或写入这些项目内的资源。如果应用必须与不在项目内的Foundry资源交互，请考虑使用无限制应用。

操作限制

操作限制定义了应用可以执行哪些API操作。与资源限制不同，您只能在平台SDK(Platform SDK)选项卡中配置操作限制。

在此处，通过API命名空间添加允许的操作。选择应用可用于与所选项目资源交互的方法。操作按API命名空间分组，对应于端点的路径；例如，/admin/ API命名空间包括所有路径为/api/{version}/admin/的端点。有关API命名空间的更多详细信息，请参阅API文档。

客户端允许操作的API级安全

开发者控制台(Developer Console)应用对受限应用强制执行API级安全，确保这些应用调用的每个端点必须显式添加到平台SDK(Platform SDK)面板的操作限制列表中。无限制应用不受这些更改的影响，将继续能够调用用户拥有必要权限的端点。请注意，无限制应用通常应仅用于程序化的、平台范围的工作流。

无限制应用

无限制(Unrestricted)应用在确定访问权限时仅考虑应用用户的权限，而不是将访问限制在预定义的资源集上。

默认情况下，自定义应用是受限的，以鼓励更严格的安全保证。在以下情况下使用无限制应用：

• 资源无法在部署时定义（例如，尚不存在的项目）。
• 您的应用必须访问项目之外的管理原语（例如，空间、组织或注册）。
• 您需要使用平台API中尚未发布的端点。

:::callout{theme="warning"} 无限制应用可以与应用用户有权访问的任何资源交互。仅对受信任的代码使用无限制应用。 :::

在授权时请求作用域

除了在开发者控制台中配置的限制之外，第三方应用还可以在认证时请求操作作用域。如上文所述，在确定访问权限时，请求的作用域将与应用的限制和用户的基础权限相交。请注意，Foundry第三方应用只能在授权时请求操作。资源访问仅由应用的资源限制和用户权限决定，不需要请求。

Foundry端点在其API文档中记录了所需的作用域。以下示例显示了一个TypeScript OAuth客户端作用域请求，用于读取本体数据和Foundry数据集：

const scopes = ["api:use-ontologies-read", "api:use-datasets-read"];

export const auth: PublicOauthClient = createPublicOauthClient(
    clientId,
    foundryUrl,
    redirectUrl,
    { scopes },
);

/**
 * 初始化客户端以与本体和平台SDK交互
 */
export const client: Client = createClient(foundryUrl, ontologyRid, auth);

空([])请求的操作作用域将默认为应用的操作限制。无限制应用没有最大允许限制，其行为取决于请求的认证授权类型：

1. 客户端凭证授权(Client Credentials grant)： 不需要请求作用域。未请求作用域的应用将被授予服务用户有权访问的所有操作。
2. 授权码授权(Authorization Code grant)： 应用必须请求作用域。在授权码流程中，人类用户同意一组请求的操作。因此，应用构建者必须定义应用需要哪些操作。这有助于最小化与权限提升相关的攻击向量。

迁移到API安全

如上文所述，2025年6月1日之后创建的开发者控制台(Developer Console)应用强制执行API级安全，以确保受限第三方应用调用的每个端点必须单独添加到客户端允许的操作列表中。对于2025年6月1日之前创建的应用，请按照下面的迁移步骤操作。

任何新的或已迁移的应用现在将限制以前允许的两种应用访问类型：底层服务端点和隐式操作授权。

无法访问底层服务端点

受限应用不允许调用底层服务API，这些是未明确记录或向用户公开的端点。

开发者控制台(Developer Console)应用客户端使用的作用域现在包含前缀use-；例如：api:use-ontologies-read而不是api:ontologies-read。这些新权限仅允许您调用Foundry平台API，并阻止调用底层服务端点。

API安全的一个重要例外是一组管理端点，这些端点设计为始终可供用户访问，用于身份识别、授权或访问调试。这些端点不适用于广泛的公共使用，因此未包含在公共Foundry API文档或平台SDK资源(Platform SDK resources)面板中。此类端点包括：

• OAuth2： /multipass/api/oauth2/...
• 用户信息： /multipass/api/me/...
• 资源访问信息： /multipass/api/authz/...
• 令牌TTL： /multipass/api/token/...
• 组织： /multipass/api/organizations/...

受限应用始终可以调用这些端点。

无隐式操作授权

随着高级API级安全的加入，每个API命名空间被严格隔离。在这些更改之前，授予一个API命名空间作用域会使应用能够访问该命名空间中的端点以及其他命名空间中的任何依赖端点。新的、更安全的API作用域（带有前缀use-）仅提供对直接授予的API命名空间的访问。这确保了应用管理员可以牢牢控制应用在其组织内可能执行的操作。

例如，被授予/ontologies/ API命名空间权限（api:use-ontologies-read）的旧版应用可以使用/admin/命名空间中的/api/v2/admin/users/getCurrent端点查询基本用户身份信息，因为多个本体端点需要这些操作进行认证。一旦迁移到改进的安全协议，如果应用仅被授予api:use-ontologies-read和api:use-ontologies-write作用域，应用将被阻止访问此用户信息，并将收到ApiUsageDenied错误。

默认情况下，所有在安全更新后创建的或已迁移到使用高级API级保护的开发者控制台(Developer Console)应用都将配置api:use-ontologies-read和api:use-ontologies-write作用域。

迁移步骤

按照以下步骤将您的开发者控制台(Developer Console)应用迁移到使用高级API安全：

1. 导航到平台SDK资源(Platform SDK resources)选项卡，然后选择迁移(Migrate)。

1. 按照对话框中的说明更新您的应用代码。如果您使用的是TypeScript SDK，请更改请求的操作作用域以使用尊重升级安全模型的新作用域。为防止临时中断，不要在添加新作用域的同时移除任何原始操作作用域。

1. 应用成功迁移后，您可以从应用代码中移除原始的、过时的作用域。

作用域前缀

Foundry为API权限使用两种作用域前缀：

作用域模式	示例	用例
api:use-*-read/write	api:use-ontologies-read	新的受限开发者控制台(Developer Console)应用。仅允许公共API调用。
api:*-read/write	api:ontologies-read	独立OAuth客户端和某些无限制应用。允许公共API调用和内部服务端点。

选择使用哪个作用域时：

• 受限应用应使用api:use-*作用域（例如，api:use-ontologies-read）。
• 独立OAuth客户端应使用api:*作用域（例如，api:ontologies-read），因为它们如上所述直接调用Foundry。注意：独立OAuth客户端是正在被无限制应用取代的旧版原语。
• 无限制应用应使用api:use-*作用域，除非它们正在查询底层Foundry服务端点。

此模式适用于所有API命名空间，包括admin、ontologies、datasets、streams等。

独立OAuth客户端 [旧版]

:::callout{theme="neutral"} 无法再从开发者控制台(Developer Console)创建独立OAuth客户端。我们建议创建无限制的开发者控制台应用。 :::

独立OAuth客户端是自定义应用的旧版轻量级替代方案。除了认证客户端本身之外，独立OAuth客户端不提供应用构建功能，如限制、指标或SDK生成。

无限制应用通过在功能齐全的自定义应用内提供同等的访问灵活性来取代独立OAuth客户端。

将独立OAuth客户端转换为无限制自定义应用的迁移步骤将在未来版本中提供。

另请参阅

• 权限(Permissions)： 了解有关用户和应用权限类型以及资源访问限制的更多信息。
• OAuth客户端(OAuth clients)： 了解如何创建和管理OAuth客户端。