--- title: API Operations description: The PingOne /environments/{{envID}}/apiServers/{{apiServerID}}/operations endpoint provides operations to create, read, update, and delete API service operations in PingOne. Each operation is defined by one or more paths, and each path must have a unique pattern. component: pingone-api page_id: pingone-api:authorize:api-access-management/api-operations canonical_url: https://developer.pingidentity.com/pingone-api/authorize/api-access-management/api-operations.html section_ids: path-parameter-pattern-syntax: Path parameter pattern syntax assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service api-server-operations-data-model: API service operations data model response-codes: Response codes --- # API Operations The PingOne `/environments/{{envID}}/apiServers/{{apiServerID}}/operations` endpoint provides operations to create, read, update, and delete API service operations in PingOne. Each operation is defined by one or more paths, and each path must have a unique pattern. ## Path parameter pattern syntax If a path pattern has a type of `PARAMETER`, the following syntax rules apply to the parameter expression: * The pattern must start with a slash. * A single `*` (wildcard) matches any character except a `/`. * A double `**` matches the rest of the path. It cannot be followed by any characters in the pattern. * A path segment can be matched using a named parameter, with syntax like `/{variable}`. * Nested named parameters are not allowed, meaning `{name1{name2}}` is an invalid expression. * Partial path segment matches are not allowed, meaning `/part1{part2}` is an invalid expression. * A literal left curly bracket, right curly bracket, backslash, or wildcard can be matched by preceding the character with a backslash: `\{, \{, \\, \*`. * The following characters are not allowed in parameter names: `'{', '}', '\', '/'`. * Parameter names must be unique within an expression, meaning `/{name1}/resource/{name1}` is an invalid expression. * ASCII control characters are invalid anywhere in the pattern. ## Assigning admin roles and permissions to this service Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to [PingOne Permissions by Service](../../platform/reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](../../platform/reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](../../platform/roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](../../platform/group-role-assignments/group-role-assignments.html). * [User Role Assignments](../../platform/users/user-role-assignments.html). Refer to [Roles Management](../../platform/roles.html) for more information. ## API service operations data model | Property | Type? | Required? | Mutable? | Description | | ------------------------------------------------ | ------------ | --------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | String | N/A | Read-only | The ID of the API service operation. This is randomly generated when the operation is created. | | `name` | String | Required | Mutable | The name of the API service operation. | | `accessControl` | Object | Optional | Mutable | The access control configuration for the operation. | | `accessControl.authentication` | Object | Optional | Mutable | Defines the authentication requirements for this operation. One or both of the `acrs` or `maxAge` fields must be provided. | | `accessControl.authentication.acrs` | Array | Optional | Mutable | The `acrs` array is currently limited to a single entry. | | `accessControl.authentication.acrs.element` | Object | Required | Mutable | The relationship reference to a PingOne authentication policy. | | `accessControl.authentication.acrs.element.id` | String | Required | Mutable | The ID of the authentication policy. | | `accessControl.authentication.acrs.element.type` | String | Required | Mutable | Identifies the authentication policy type. Valid values are `PINGONE`, which identifies a sign-on policy, and `DAVINCI`, which identifies a flow policy. | | `accessControl.authentication.maxAge` | Number | Optional | Mutable | Specifies the maximum acceptable time in seconds since the user was last authenticated. If provided, the value must be a nonzero positive integer. | | `accessControl.group` | Object | Optional | Mutable | The group membership requirements for the operation. The `groups` array must be non-empty when the `group` object is included. The `groups` array must not contain more than 25 elements. | | `accessControl.group.groups` | Array | Required | Mutable | The list of groups that define the access requirements for the operation. The end user must be a member of one or more of these groups to gain access to the operation. This is a required property if `accessControl.group` is set. The ID must reference a group that exists at the time the data is persisted. There is no referential integrity between a group and this configuration. If a group is subsequently deleted, the access control configuration will continue to reference that group. | | `accessControl.group.groups.element` | Relationship | Required | Mutable | The ID of the group, wrapped in an object, for future extensibility. This is a required property if `operations.value.accessControl.group` is set. | | `accessControl.group.groups.element.id` | String | Required | Read-only | A UUID that specifies the group ID. This is a required property if `accessControl.group` is set. | | `accessControl.permission` | Object | Optional | Mutable | Defines the application permission requirements for the operation. | | `accessControl.permission.id` | string | Required | Mutable | An application permission ID that defines the access requirements for the operation. The end user must be entitled to the specified application permission to gain access to the operation. This is a required property if `accessControl.permission` is set. | | `accessControl.scope` | Object | Optional | Mutable | Defines the scope membership requirements for the operation. | | `accessControl.scope.matchType` | String | Optional | Mutable | An enumeration defining the match type of the scope rule. `ALL` means the client must be authorized with all scopes configured in the `scopes` array to obtain access. `ANY` means the client must be authorized with one or more of the scopes. | | `accessControl.scope.scopes` | Array | Required | Mutable | A list of scopes that define the access requirements for the operation. The client must be authorized with `ANY` or `ALL` of the scopes to be granted access, depending on the `matchType` configuration. | | `accessControl.scope.scopes.element` | Object | Required | Mutable | The relationship reference to a PingOne scope. | | `accessControl.scope.scopes.element.id` | String | Required | Read-only | The ID of the scope. | | `methods` | Array | Optional | Mutable | The methods that define the operation. No duplicates are allowed. Each element must be a valid HTTP token, according to [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230), and cannot exceed 64 characters. An empty array is not valid. To indicate that an operation is defined for every method, the `methods` array should be set to null. The `methods` array is limited to 10 entries. | | `methods.element` | String | Optional | Mutable | The name of the HTTP method. This value is case-sensitive. | | `paths` | Array | Required | Mutable | The paths that define the operation. The same literal pattern is not allowed within the same operation (the pattern of a `paths` element must be unique as compared to all other patterns in the same `paths` array). However, the same literal pattern is allowed in different operations (for example, OperationA, `/path1`, OperationB, `/path1` is valid). The `paths` array is limited to 10 entries. | | `paths.element` | Object | Required | Mutable | The defined pattern that identifies the parent operation. | | `paths.element.pattern` | String | Required | Mutable | The pattern used to identify the path or paths for the operation. The semantics of the pattern are determined by the type. For any type, the pattern can contain characters that are otherwise invalid in a URL path. Invalid characters are handled by performing matching against a percent-decoded HTTP request target path. This allows an administrator to configure patterns without worrying about percent encoding special characters. When the `type` is `PARAMETER`, the syntax outlined in the table below is enforced. Additionally, the pattern must contain a wildcard, double wildcard or named parameter. When the `type` is `EXACT`, the pattern can be any byte sequence except for ASCII control characters such as line feeds or carriage returns. The length of the pattern cannot exceed 2048 characters. The path pattern must not contain empty path segments such as `/../`, `//`, and `/./`. | | `paths.element.type` | String | Required | Mutable | The type of the pattern. Options are `EXACT` (the verbatim pattern is compared against the path from the request using a case-sensitive comparison) and `PARAMETER` (the pattern is compared against the path from the request using a case-sensitive comparison, using the syntax below to encode wildcards and named parameters). | | `policy.id` | String | Optional | Read-only | The ID of the root policy. | ## Response codes | Code | Message | | ---- | --------------------------------------------------------------------- | | 200 | Successful operation. | | 201 | Successfully created. | | 204 | Successfully removed. No content. | | 400 | The request could not be completed. | | 401 | You do not have access to this resource. | | 403 | You do not have permissions or are not licensed to make this request. | | 404 | The requested resource was not found. |