How to Integrate REST API with Pearl Diver

Authentication

1. Authorization Request: The client application initiates the authentication process by requesting authorization from the user. This typically involves redirecting the user to the Blackpearl Group Pearl Diver authorization endpoint and specifying the desired scopes, including openid, profile, email, and offline_access.

Example Authorization Request (in your code, the actual URL and parameters may vary):

2. User Authentication: The user is presented with a login screen and is prompted to grant or deny access to their data. If the user grants access, they are redirected back to the client application's specified redirect URI with an authorization code.

Example Redirect URL:

3. Token Exchange: The client application exchanges the authorization code for an access token. This exchange is made directly with the Blackpearl Group Pearl Diver token endpoint.

Example Token Exchange Request:

In this request, the client provides the authorization code received in step 2, along with its client ID and client secret for authentication.

4. Access API: With a valid access token, the client application can now access the Blackpearl Group Pearl Diver REST API on behalf of the user. Include the access token in the Authorization header of your API requests.

Example API Request (using the access token):

5. Refreshing the Access Token: Access tokens may expire after a certain period. To maintain ongoing access without requiring the user to reauthenticate, the client can use the refresh token to obtain a new access token. This is done by making a request to the token endpoint with the refresh token.

Example Token Refresh Request:

 

1. POST https://auth.pearldiver.io/oauth/token?audience=pearldiverapi
2. Content-Type: application/x-www-form-urlencoded
4. grant_type=refresh_token
5. refresh_token=REFRESH_TOKEN
6. client_id=YOUR_CLIENT_ID
7. client_secret=YOUR_CLIENT_SECRET

 

The client provides the refresh token it obtained in step 3, along with its client ID and client secret. In response, it receives a new access token and, a new refresh token.

Remember to store the new access token and, the new refresh token securely for continued API access. The use of refresh tokens allows your application to maintain access without user intervention even when access tokens expire.

Please replace placeholders such as YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URI, and desired_scope with your specific values when implementing OAuth 2.0 for the Blackpearl Group Pearl Diver REST API.

 

Authorization

Authorization is based on the user used in the authentication process. The user must have a valid Pearl Diver account to be authorized with the REST API.

Status codes

The Pearl Diver REST API uses the standard HTTP status codes . REST failures (400s, 500s) are returned without a response body.

Refresh Token Rotation

Refresh token rotation is a security measure used in authentication protocols, particularly OAuth 2.0, to enhance the security of long-lived refresh tokens. Refresh tokens are typically longer-lived and can be used to request new access tokens after the shorter-lived access tokens expire. With refresh token rotation, every time an application exchanges a refresh token to get a new access token, a new refresh token is also returned. Therefore, you no longer have a long-lived refresh token that, if compromised, could provide illegitimate access to resources. As refresh tokens are continually exchanged and invalidated, the threat is reduced.

Refresh Token Expiration

Refresh tokens can be a target for abuse if leaked because they can be used to acquire new access tokens. Refresh Token Rotation issues a refresh token that expires after a preset lifetime. After expiration, the user gets a new refresh token or a new access token/refresh token pair.

Pearl Diver rest API have the following refresh token expiration settings

• Absolute Lifetime: Set a refresh token or refresh token family lifetime after which the user must re-authenticate before being issued a new access token.

 

 

• Inactivity Lifetime: Set the inactivity lifetime of issued refresh tokens to expire if the user is not active in your application during a specified period.

 

 

Using the REST API

Audience

Modal references

Phone

phoneType string  OPTIONAL

Address

Company