Documentation

Accessing an API in the DHCS Developer Portal

Overview

In order to access an API on the developer portal you must request and obtain your client_id and client_secret for that API. Procurement is very straightforward in the developer portal.

Step 1: Request Access to an API

Locate the API in the API Catalog

You can view accessible APIs from multiple locations on the portal.

  • Home page: Select API Catalog tile
  • Navigation bar: Select the API Catalog tab

Select the API

On the API Catalog page, find the API you want to access and click its tile.

This will open a Swagger page displaying the API endpoints for review.

To learn more about searching our API Catalog, please see: Search and discover an API

Access the API request form

Once you are certain this is the API you want to access, select the Request API Access button in the upper right corner of the page.

You can view an API's Swagger documentation without logging into the portal, but only authenticated users can submit API requests.
If you need assistance, see the Registration & Login page.

Fill in required fields

Some fields will be pre-filled with information from your Ping Identity.

From the Request Access modal, complete all required fields (*). If fields are pre-filled, confirm the information is correct.

Once you have completed all required fields, select the Submit request button in the lower right corner of the modal.

What to expect from the Request Access process

The Request Access modal submission kicks off an asynchronous process:

  1. An acknowledgment of your pending request will be sent to the email address you provided in the form.
  2. The API owner receives your API request email.
  3. Once the API owner responds, you will receive an email notifying you whether your access has been approved.

Step 2: Retrieve Credentials (Client ID and Client Secret)

View your Access Requests

Once the API owner has approved your request, you may visit the Access Requests page to retrieve your credentials using several different methods:

  • Email: Select the View Requests button at the bottom of your confirmation email
  • Portal: Select the Access Requests tab in the navigation bar

For more information about API access requests, see the Getting Started Guide.

Store your credentials

Locate your approved request

On the API Access Requests page, locate and select your approved request and select the Retrieve Credentials button on the right.

A confirmation dialog will display with your new credentials.

Receive your credentials

The Retrieve Credentials button will be disabled once the modal is closed.

Store the credentials in a secure location, such as HashiCorp’s Vault product or another protected storage, before selecting the Confirm button. You can retrieve credentials only once.

Credential Expiration

Every issued client_secret expires 90 days after it is created. Rotating a credential re-anchors this to a new 90-day window from the rotation timestamp.

The Access Requests page tracks this for you in the Expiry column:

  • The request's status shows Expiring Soon once you are within 30 days of expiration.
  • The status shows Expired once the expiry date has passed.

An expired client_secret can no longer be used to retrieve a JWT token, so plan to rotate or replace your credential (see below) before it expires.

Step 3: Manage Your Credentials (Rotate and Revoke)

Once credentials have been retrieved for an approved request, the Access Requests page displays two additional actions on that request row: Rotate Credential and Revoke Credential.

Rotating a Credential

Use Rotate Credential when you need to replace your current client_secret without losing access to the API — for example, on a scheduled security cadence, or immediately if you suspect the secret has been exposed.

Selecting Rotate Credential opens a confirmation dialog warning that rotating will immediately invalidate the current client_secret and generate a replacement. On confirmation:

  1. The current client_secret is invalidated immediately. Your client_id does not change.
  2. A new client_secret is generated and displayed once in the credential dialog. Copy it to your secure storage right away, you can view it only once.

Your integration will stop working until you update it with the new secret. Plan the rotation for a maintenance window, or coordinate the cutover with your deployment.

Revoking a Credential

Use Revoke Credential to permanently invalidate the client_id/client_secret for that request. Unlike rotation, revoking issues no replacement.

Selecting Revoke Credential opens a confirmation dialog warning that revoking will permanently invalidate the credential and that no replacement will be issued. On confirmation, the credential is invalidated immediately and the request's status changes to Revoked.

To regain access to the API, you must submit a new access request from the API Catalog — a revoked request cannot be reactivated or re-provisioned.

Canary-Style Cutover with a Second Access Request

Rotating replaces your client_secret immediately, which means your integration stops working until you deploy the new secret. If you need a zero-downtime cutover instead — for example, ahead of the 90-day expiration, or to stage a gradual rollout across multiple application instances — submit a second, independent access request for the same API rather than rotating your existing credential in place.

  1. From the API Catalog, find the same API again and select Request API Access, completing the request form as you did originally (see Step 1).
  2. Once the new request is approved, retrieve its credentials from the Access Requests page the same way you did the first time (see Step 2). This issues a brand-new, independent client_id/client_secret pair — your original credential stays active and untouched.
  3. Update your application to use the new credential pair. For a canary-style rollout, cut a subset of instances or traffic over first, leaving the rest on the original pair, and monitor both before completing the cutover.
  4. Once you've fully cut over and confirmed the new credential is working, select Revoke Credential on the original request's row to retire it.

Because the new request is a separate row on the Access Requests page, it has its own independent 90-day expiration clock — rotating, expiring, or revoking one credential has no effect on the other.

Step 4: Retrieve JWT Tokens

Retrieve the JWT token to access the requested API using your Client ID and Client Secret

JWT Authentication with an API in the DHCS Developer Portal