Defining your API in PingOne Authorize - PingOne - PingOne Cloud Platform - PingOne Authorize - PingOne Services

PingOne Cloud Platform

PingOne Cloud Platform
PingOne Cloud Platform
Product documentation
Guide > Administrator Guide

Define a managed API service to represent your API so that PingOne Authorize can help your API gateway enforce access control.

A managed API service enables PingOne Authorize to recognize requests for your API and instructs the API gateway to allow access from authorized clients only and block access from unauthorized clients.

An API service definition includes a pointer to the API and to the specific parts of the API that you want to protect. The definition includes an option to enable custom access control policies for complex authorization scenarios. The definition also specifies whether directory services and access token validation are managed by PingOne or managed externally.

You must deploy the API service after you make configuration changes, such as updating a setting or adding an operation.

  1. Go to Authorization > API Services.
  2. Click the + icon next to API Services to add an API service.
  3. For the Name, enter a name that identifies the API service.

    The name must be unique across all API services and resources.

  4. Enter one or more Base URLs for the API represented by the API service.

    You can enter multiple URLs to support aliases for the same service, such as a vanity URL in addition to the domain URL. To add another URL, click + Add Base URL. URLs must be valid.

    Screen capture showing the Name, Base URLs, and Decision Endpoint fields and directory and token source options in the New API Service window in PingOne.
  5. To enable custom policies for the API service and its operations, select the Enable Custom Policies check box.

    This generates a policy tree for the API service, enabling you to add your own custom authorization policies for the APIs managed by this API service.


    After you save the API service, you can't change this setting. This setting is not available if you select External Services in the next step. Custom policies are enabled by default for external token service providers.

  6. Select a user directory and token source:
    • PingOne SSO: PingOne manages user directory services and access token validation for the API service. This is the default option.
    • External Services: The API gateway manages access token validation services through external providers, such as PingFederate. This requires you to configure your API gateway to pass validated token claims to PingOne in decision requests.

    After you save the API service, you can’t change whether the directory and token source are managed by PingOne or by external providers.

  7. Click Save.

    A corresponding resource is created that establishes a relationship between the API service and PingOne in order to define the audience for the API service’s access token.

  8. Click Deploy.

    If you selected External Services in step 6, PingOne Authorize is now configured to recognize the API.

    If you selected PingOne SSO in step 6, complete steps 9 - 12.

  9. On the Advanced tab, click the Pencil icon to add a scope.
    Screen capture of the API Services Advanced tab in PingOne.
  10. In the Name field, enter a name for the scope.

    The scope defines which resources an API client can access. An application requests a scope for the resource associated with an API service in order to set the audience for the access token. For consistency, you might use a lowercase version of the API service name and replace spaces with hyphens.

    Screen capture showing the scope name in Configure Scopes on the API Services Advanced tab in PingOne.
  11. Optional: Enter a description for the scope.
  12. Click Save, and then click Deploy.

    PingOne Authorize is now configured to recognize the API.