--- title: Defining operations for protected actions description: Operations in PingOne Authorize enable you to use built-in access control rules or custom policies to control access to API actions. component: pingone page_id: pingone:authorization_using_pingone_authorize:p1az_add_api_service_operations canonical_url: https://docs.pingidentity.com/pingone/authorization_using_pingone_authorize/p1az_add_api_service_operations.html revdate: December 2, 2025 section_ids: built_in_access_control_rules: Built-in access control rules custom-policies: Custom policies steps: Steps next-steps: Next steps --- # Defining operations for protected actions Operations in PingOne Authorize enable you to use built-in access control rules or custom policies to control access to API actions. An API service operation is a method and path combination that matches a client request to the API. Add operations for API requests that you want to protect. | | | | - | -------------------------------------------------------------------------- | | | You can define up to 25 operations for each API service in an environment. | When PingOne is managing user directory services and access token validation for an API service, you can define built-in access control rules and custom policies for an operation. When these services are managed externally, you can define custom policies for an operation, but you can't configure built-in access control rules. ## Built-in access control rules Built-in access control rules grant access to protected operations based on the following factors: * User membership in groups Before you grant access based on group membership, you must [add users](../directory/p1_adduser.html) and [create groups](../directory/p1_create_group.html) in PingOne. * Authorized OAuth scopes Scopes determine the resources that a client can access. For example, a banking application might use scopes to control the kinds of data shared with third-party applications. * Authorized permissions Before you grant access based on permissions, you must [define permissions](../applications/p1_add_application_permissions.html) for the application resources that you want to protect. * Authentication policy This rule defines the authentication policy that the decision service requires when evaluating whether to allow access to the operation. The authentication policy provides context about the authentication method or assurance level required to get an access token for the protected resource. You can use this rule to implement step-up authentication for the protected resource. Learn more in [Step-up authentication](../authentication/p1_stepup_authentication_for_apis.html). * Time since last authentication This rule defines the maximum acceptable amount of time since the last authentication event used to get an access token for the protected resource. You can use this rule to implement step-up authentication for the protected resource. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When you use the **authentication policy** and **time since last authentication** basic rules with the [Amazon Web Services (AWS) integration kit](p1_az_amazon_web_services_integration.html), AWS doesn't return the full step-up [challenge response](../authentication/p1_stepup_authentication_for_apis.html#request_requires_additional_auth). When these rules produce deny decisions, AWS returns a simple deny response with an HTTP status code. | PingOne Authorize automatically generates [policies](p1az_policies.html) for built-in access control rules and deploys them when you [deploy](p1az_deploying_api_services.html) the associated API service. ## Custom policies Custom policies handle more complex authorization scenarios, such as evaluating context by pulling in risk scores to determine access. You can enable custom policies when you define an API service or by editing the API service later. The following steps provide information about configuring built-in access control rules for an operation. Learn more about custom policies in [Adding custom policies for API services and operations](p1az_adding_custom_policies_for_api_services_and_operations.html). ## Steps 1. Go to **Authorization > API Services**. 2. Select your API service, and then click the **Operations** tab. 3. To create a new operation, click **Define Operation**. 4. Click **Methods**, and then select one or more methods for the operation. Press Tab or click outside the list to close it. ![Screen capture showing the expanded Methods list in the Create Operation window.](_images/pry1648077184061.png) 5. Enter one or more API **Paths** for the operation. Paths must start with a slash (/) and match requests for resources and subresources exactly unless you use wildcards or parameters. * A single wildcard (\*) represents one path segment. * A double wildcard (\*\*) represents one or more segments at the end of the path. * Surround parameters with curly braces ({}). You can add attributes that represent path parameters to make them easy to use in custom policies. Learn more in [API Access Management attributes](p1_az_built_in_attributes.html#p1-aam-attr). For examples of path definitions and matching requests for account resources and subresources, such as transactions, expand the following section. Only a few of the possible matches are shown for paths with wildcards. Learn more in [API Services](https://developer.pingidentity.com/pingone-api/authorize/api-access-management/api-services.html) in the PingOne Authorize API Reference documentation. > **Collapse: Example path definitions and matching requests** > > | Path | Examples of matching requests | > | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | `/accounts/{accountId}/transactions/*` | `/accounts/123/transactions` `/accounts/123/transactions/` `/accounts/123/transactions/456` `/accounts/123/transactions/details` | > | `/accounts/*/transactions/*` | `/accounts/123/transactions` `/accounts/123/transactions/` `/accounts/123/transactions/456` `/accounts/123/transactions/details` | > | `/accounts/{accountId}/**` | `/accounts/123/transactions` `/accounts/123/transactions/` `/accounts/123/transactions/456` `/accounts/123/transactions/details` `/accounts/123/transactions/details/statement` `/accounts/123/settings` | > | `/accounts/{accountId}/transactions/` | `/accounts/123/transactions/` Matching requests must end with a slash (/). | > | `/accounts/{accountId}/transactions` | `/accounts/123/transactions` Matching requests must not end with a slash (/). | To add another path, click **[icon: plus, set=fa]Add Path**. 6. For **Name**, enter a name that describes the operation. | | | | - | ---------------------------------------------------------------------------------------------------- | | | You can change the default name, which consists of the method and path separated by **request for**. | ![Screen capture of the Create Operation window showing Method, Paths, and Name settings.](_images/nma1648077407024.png) 7. If user directory services and access token validation are managed externally for the API service, click **Save**, then click **Deploy**. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Built-in access control rules are not available in this situation. Instead, use your external providers, such as PingFederate and PingDirectory, to configure authorized scopes and user groups. | 8. To define access control rules, click **Next**. 9. (Optional) Define a rule based on group membership: ![Screen capture of the Create Operation window showing Define Access Rules settings.](_images/pnx1648077629407.png) 1. Select the **The user must be a member of any of these groups** checkbox. 2. Click the **Groups** list, and then select one or more groups. Press Tab or click outside the list to close it. ![Screen capture showing the expanded Groups list in the Create Operation window.](_images/tqg1648077722666.png) 10. (Optional) Define a rule based on authorized scopes: 1. Select the **Client must be authorized with these scopes** checkbox. 2. Click the **Scopes** list, and then select one or more scopes. Press Tab or click outside the list to close it. ![Screen capture showing the expanded Scopes list in the Create Operation window.](_images/xaa1668541284988.png) 3. (Optional) To add a new scope, in the **Scopes** list, enter the name of the scope, and then press Enter. 4. Click the toggle to change whether all or any of the scopes must be authorized: * **All** (default): Allows access if a client is authorized for all of the scopes. This is equivalent to adding a Boolean AND operator between scopes. * **Any**: Allows access if a client is authorized for any of the scopes. This is equivalent to adding a Boolean OR operator between scopes. | | | | - | --------------------------------------------------------------------- | | | **All** and **Any** have the same effect when there's only one scope. | 11. (Optional) Define a rule based on permissions: 1. Select the **The user must have this permission** checkbox. 2. Click the **Permission** list, and then select a permission. The list includes all of the permissions that are available for the PingOne resource associated with the API service. ![Screen capture showing the expanded Permission list in the Create Operation window.](_images/ovy1704992638259.png) 12. (Optional) Define a rule based on the authentication policy: 1. Select the **The user must be authenticated with this authentication policy** checkbox. 2. In the policy list, select a flow or sign-on policy. The list includes all of the authentication flows and sign-on policies that are available in the environment. ![Screen capture showing the expanded flow and sign-on policy list in the Create Operation window.](_images/p1az-aam-api-services-operation-authn-policy-list.png) | | | | - | -------------------------------------------------------------------------------------------------------------------------------------- | | | If an authentication flow or sign-on policy is renamed or deleted, you must update this rule accordingly and redeploy the API service. | 13. (Optional) Define a rule based on time since last authentication: 1. Select the **The user must be authenticated within the last** checkbox. 2. Enter the maximum amount of time to allow since the last authentication event, in seconds. The number of seconds must be greater than 0. ![Screen capture showing the expanded elapsed time list in the Create Operation window.](_images/p1az-aam-api-services-operation-authn-time-list.png) 14. Click **Save**. 15. Click **Deploy**. ## Next steps If you configured a scope-based rule for the operation, make sure that you grant the same scopes to your PingOne application to ensure that clients are allowed to access the API operation. To do this, edit the list of allowed scopes on the application's **Resources** tab. Learn more in [Editing scopes for an application](../applications/p1_edit_scopes_for_an_application.html). If you configured a permission-based rule for the operation, make sure that you [assign permissions to roles](p1_az_adding_application_roles.html), and assign roles to users.