--- title: API Services description: The PingOne /environments/{{envID}}/apiServers endpoint provides operations to create, read, update, and delete API services in PingOne. An API service models a customer's APIs, which are then protected by the PingOne API access management service. component: pingone-api page_id: pingone-api:authorize:api-access-management/api-services canonical_url: https://developer.pingidentity.com/pingone-api/authorize/api-access-management/api-services.html section_ids: assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service api-server-data-model: API service data model path-parameter-pattern-syntax: Path parameter pattern syntax api-server-limit-filter-data: Limiting and filtering data response-codes: Response codes --- # API Services The PingOne `/environments/{{envID}}/apiServers` endpoint provides operations to create, read, update, and delete API services in PingOne. An API service models a customer's APIs, which are then protected by the PingOne API access management service. | | | | - | ------------------------------------------------------------ | | | PingOne enforces a limit of 25 API services per environment. | ## 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 data model | Property | Type? | Required? | Mutable? | Description | | -------------------------------------------------- | ------------ | --------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accessControl.custom` | Object | Optional | Mutable | Defines if the operation will use custom policy rather than the "Group" or "Scope" `accessControl` requirement. | | `accessControl.custom.enabled` | Boolean | Optional | Mutable | If `TRUE`, custom policy will be used for the endpoint. Defaults to `FALSE`. | | `authorizationServer` | Object | Required | Mutable | A container for properties related to the authorization server that will issue access tokens used to access the APIs. | | `authorizationServer.externalOAuthServer` | Object | Optional | Mutable | A container object for fields related to the API service's external OAuth 2 authorization server. Must not be provided if `authorizationServer.type` is `PINGONE_SSO`. | | `authorizationServer.externalOAuthServer.audience` | String | Required | Mutable | The expected audience for incoming access tokens issued by the External OAuth Server. The runtime will reject bearer tokens not issued for this audience by checking for a matching value in the aud claim. The maximum length is 1024. | | `authorizationServer.externalOAuthServer.id` | UUID | Required | Mutable | The ID of the related External OAuth Server. | | `authorizationServer.resource` | Relationship | Required | Mutable | The resource defines the characteristics of the OAuth 2.0 access tokens used to get access to the APIs on the API service such as the audience and scopes. Must not be provided if `authorizationServer.type` is `EXTERNAL`. | | `authorizationServer.resource.id` | String | Required | Mutable | The UUID of the custom PingOne resource. This property must identify a PingOne resource with a `type` property value of `CUSTOM`. | | `authorizationServer.type` | String | Optional | Mutable | The type of authorization server that will issue access tokens. Valid options are `PINGONE_SSO` or `EXTERNAL`. Defaults to `PINGONE_SSO`. Must be the same value as the `directory.type`. If `PINGONE_SSO`, the `authorizationServer.externalOAuthServer` field must not be provided. If `EXTERNAL`, the `authorizationServer.resource` field must not be provided. | | `baseUrls` | Array | Required | Mutable | The possible base URLs that an end-user will use to access the APIs hosted on the customer's API service. Multiple base URLs may be specified to support cases where the same API may be available from multiple URLs (for example, from a user-friendly domain URL and an internal domain URL). Base URLs must be valid absolute URLs with the `https` or `http` scheme. If the path component is non-empty, it must not end in a trailing slash. The path must not contain empty backslash, dot, or double-dot segments. It must not have a query or fragment present, and the host portion of the authority must be a DNS hostname or valid IP (IPv4 or IPv6). The length must be less than or equal to 256 characters. | | `directory` | Object | Optional | Mutable | A container object for fields related to the user directory used to issue access tokens for accessing the APIs. If not provided, the `directory.type` will default to `PINGONE_SSO`. | | `directory.type` | String | Required | Mutable | The type of directory that will be used to issue access tokens. Valid options are `PINGONE_SSO` or `EXTERNAL`. Defaults to `PINGONE_SSO`. Must be the same value as the `authorizationServer.type`. | | `id` | String | Optional | Mutable | The resource's unique identifier. | | `name` | String | Required | Mutable | The API service resource name. The `name` value must be unique among all API services, and it must be a valid resource name. | | `policy.id` | String | Optional | Read-only | The ID of the root policy. | ### 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 captured with syntax like `/{variable}`. * Nested captures 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. ## Limiting and filtering data You can limit the number of results returned on the [Read API Services](api-services/read-api-servers.html) request with the `limit` parameter. Refer to [Paging and ordering collections](../../platform/reference/paging-ordering-collections.html) for more information about use of the `limit` parameter, as well as other methods of controlling pagination. You can filter response data by applying a SCIM filtering expression to the [Read API Services](api-services/read-api-servers.html) request. These SCIM operators can be applied to the following attributes: * `eq` (equals) Supported attributes: `authorizationServer.externalOAuthServer.id` ## 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. |