Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

back

DPoD API

Getting Started Using the DPoD API

search

Getting Started Using the DPoD API

Getting Started Using the DPoD API

This guide provides an introduction to using the Data Protection on Demand API, it provides example commands for completing basic DPoD API requests and operations. Please refer to the DPoD API Guide for more information about available endpoints, parameters and requests. If you encounter issues, please refer to this guide for basic advice and recommendations.

Authorization Requests

DPoD API requires a JSON Web Token (JWT) generated from Platform Credentials or Service Credentials to authorize requests over the API. Generating a JWT using Platform or Service credentials returns a "access_token": "<bearer_access_token>" which is used in subsequent requests for authenticating over the API.

Endpoint availability is restricted to the scope of your Platform Credentials or Service Credentials. Refer to the Security section of the DPoD API Guide for more information. This guide can be completed using platform or service credentials.

Platform Credentials

Service provider platform credentials allow Service Provider Administrators to access and manage tenants, users and reports using the DPoD API.

Tenant administrator and application owner platform credentials allow Tenant Administrators and Application Owners to manage Luna Cloud HSM Services, Luna Cloud HSM Service Client, service credentials and subscriber groups using the DPoD API.

Generating Platform Credentials

Generate a set of platform credentials for authenticating to the DPoD API.

Select the Credentials tab and click on Create Platform Credentials. The Generate Platform Credentials window displays.

On the Review Permissions page, verify the entitlements for the credentials you are about to create, and enter a name in the Credentials Name field. Click Next.

On the Summary page, click the Copy to Clipboard icon and paste the Client Secret in a .txt file. Click Close.

Copy and save your Client Secret in a secure location. DPoD does not maintain a record or copy of the Client Secret. Treat your copy of the Client Secret with all the precautions you would normally take to protect a password. You can reset the platform credentials client secret in the Credentials Table.

Resetting/Deleting Platform Credentials

Reset the platform credentials client secret or delete the platform credentials set through the Credentials Table.

Select the Credentials tab and scroll down to the Credentials Table. In the Credentials Table, identify the platform credential you would like to manage and open the drop-down menu in the Actions column. From this menu you can:

  • Reset Secret: Resets the Client Secret and provides the user with a new Client Secret.
  • Delete: Deletes the credentials from DPoD, the credentials are no longer usable.

Copy and save your Client Secret in a secure location. DPoD does not maintain a record or copy of the Client Secret. Treat your copy of the Client Secret with all the precautions you would normally take to protect a password.

Service Credentials

Service credentials allow users to access and consume a Luna Cloud HSM Service over the DPoD API.

Service Credentials allow Tenant Administrators, and Application Owners to access and consume services using the DPoD API.

Generating Service Credentials

For more information about the requests and endpoints listed here, please download and refer to the DPoD API Guide.

Generate a set of platform credentials for authenticating to the DPoD API.

Select the Services tab and click on My Services. Identify the service that you would like to generate service credentials for and click on the services name in the Name column. Click the Credentials tab in the sub-menu.

Click on Create Service Credentials. The Generate Service Credentials window displays.

On the Review Permissions page, verify the entitlements for the credentials you are about to create, and enter a name in the Credentials Name field. Click Next.

On the Summary page, click the Copy to Clipboard icon and paste the Client Secret in a .txt file. Close the wizard.

Copy and save your Client Secret in a secure location. DPoD does not maintain a record or copy of the Client Secret. Treat your copy of the Client Secret with all the precautions you would normally take to protect a password.

Deleting Service Credentials

Select the Services tab and click on My Services. Click the Credentials sub-menu. In the Credentials Table, identify the service credential you would like to remove and click the Trash can icon in the Actions column.

Generating a JWT

To obtain a JWT you authenticate to your DPoD tenant log in URL OAtuh2 endpoint. You provide the Client ID and Client Secret, generated from your Platform Credentials or Service Credentials. The output of the JWT request, the <bearer_access_token>, is required for authenticating requests over the DPoD API.

The JWT expires after 1 hour. In the event of a JWT expiration, you need to regenerate the JWT to continue executing commands over the API.

API Request

Send an API request to your enterprise tenant log in server endpoint. This endpoint implements an OAuth2 client credentials grant, returning a JWT in the response body.

The contents of the output "access_token":"<bearer_access_token>" is your JWT. Insert the <bearer_access_token> value into the "Authorization: Bearer <bearer_access_token>" header when making requests to the API endpoint.

URL endpoint: /oauth/token

Method: POST

Content-Type: application/x-www-form-urlencoded

Body: Provide your Client Id and Client Secret in the request body, as well as the grant_type=client_credentials parameter.


grant_type=client_credentials&client_id=<insert_clientId>&client_secret=<client_secret>

Authentication Domain

To generate your JWT token you need to make the request to your authentication domain. To determine your authentication domain, access your DPoD tenant log in screen and copy the URL. Remove /login and append /oauth/token.

Region Authentication Domain
https://<tenant>.na.market.dpondemand.io/ https://<tenant>.uaa.system.snakefly.dpsas.io/oauth/token
https://<tenant>.eu.market.dpondemand.io/ https://<tenant>.uaa.system.pegasus.dpsas.io/oauth/token

Linux NA Example


curl -X POST https://<tenant>.uaa.system.snakefly.dpsas.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded"
  -d "grant_type=client_credentials&client_id=<insert_clientId>&client_secret=<insert_client_secret>"

Linux EU Example


curl -X POST https://<tenant>.uaa.system.pegasus.dpsas.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded"
  -d "grant_type=client_credentials&client_id=<insert_clientId>&client_secret=<insert_client_secret>"

Linux Example Output


{
  "access_token": "<eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vc2FuZGJveC1jYS51YWEuc3lzdGVtLnNuYWtlZmx5LmRwc2FzLmlvL3Rva2VuX2tleXMiLCJraWQiOiJzYW5kYm94LWNhLWtleTEiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiJkNzVhMTkzMThlYTU0YjlhYTYzNGVhMTJiZjFmZTAwYiIsInN1YiI6IjA3ZGJlNGViLTFkZjUtNGU5MC1iZjJhLWM4NTc1M2MxNTY5ZiIsImF1dGhvcml0aWVzIjpbImRwb2QudHVpZC4yMmFhZmYxNi1iOTY5LTRjZTctODUxMC03ZDk0OTNhOTg0MmYiLCJkcG9kLnR1aWQuMjJhYWZmMTYtYjk2OS00Y2U3LTg1MTAtN2Q5NDkzYTk4NDJmLnNndWlkLjMzODgyZWY1LTYyMzQtNGNiYy1hOWMxLWM4YjczZjFlZmRhOCIsImRwb2QudGVuYW50LmFwaV9hcHBvd25lciJdLCJzY29wZSI6WyJkcG9kLnR1aWQuMjJhYWZmMTYtYjk2OS00Y2U3LTg1MTAtN2Q5NDkzYTk4NDJmIiwiZHBvZC50ZW5hbnQuYXBpX2FwcG93bmVyIiwiZHBvZC50dWlkLjIyYWFmZjE2LWI5NjktNGNlNy04NTEwLTdkOTQ5M2E5ODQyZi5zZ3VpZC4zMzg4MmVmNS02MjM0LTRjYmMtYTljMS1jOGI3M2YxZWZkYTgiXSwiY2xpZW50X2lkIjoiMDdkYmU0ZWItMWRmNS00ZTkwLWJmMmEtYzg1NzUzYzE1NjlmIiwiY2lkIjoiMDdkYmU0ZWItMWRmNS00ZTkwLWJmMmEtYzg1NzUzYzE1NjlmIiwiYXpwIjoiMDdkYmU0ZWItMWRmNS00ZTkwLWJmMmEtYzg1NzUzYzE1NjlmIiwiZ3JhbnRfdHlwZSI6ImNsaWVudF9jcmVkZW50aWFscyIsInJldl9zaWciOiIzY2I3ODM3IiwiaWF0IjoxNTk2ODI1NzU4LCJleHAiOjE1OTY4MjkzNTgsImlzcyI6Imh0dHBzOi8vc2FuZGJveC1jYS51YWEuc3lzdGVtLnNuYWtlZmx5LmRwc2FzLmlvL29hdXRoL3Rva2VuIiwiemlkIjoiOWQ4MDYwY2ItNTg1OS00YjI5LThlZGMtZTJiYTk5OGNmZDJhIiwiYXVkIjpbImRwb2QudHVpZC4yMmFhZmYxNi1iOTY5LTRjZTctODUxMC03ZDk0OTNhOTg0MmYuc2d1aWQiLCIwN2RiZTRlYi0xZGY1LTRlOTAtYmYyYS1jODU3NTNjMTU2OWYiLCJkcG9kLnRlbmFudCIsImRwb2QudHVpZCJdfQ.Q2K2EJD82pbeiP3d5Hv_kpUR-M3-sbhNlAHrej3rtXS0dWMOfZXqxY_CzfYbbpIUws2WskE6MOB_SbxkSoDEcGGQnfsleK4sXL2QFwVPmlUaQCOZSqjFPK8qnKiS3DcUaCwL5AvVGyhm6yd1TQ-R68pXsosQbPJNfjX9VKD5APi_qZh5tHFOfkiVHfSXcZrh81DnTxZoDlrly7886U8ADcKwCWIgH3WpyCaFS8QNtb2qucvsPZbBfES2AX_1e5rDgqQ5l01nQQnxLTQs0uBSuUjLDKtQwCX6iyQ0ZbNaHodMwtVH7nQNL7MAot29bjZjjn4bzwEwppLpGLoc258LNg>",
  "token_type":"bearer",
  "expires_in":3599,
  "scope":"dpod.tuid.22aaff16-b969-4ce7-8510-7d9493a9842f dpod.tenant.api_appowner dpod.tuid.22aaff16-b969-4ce7-8510-7d9493a9842f.sguid.33882ef5-6234-4cbc-a9c1-c8b73f1efda8>","jti":"d75a19318ea54b9aa634ea12bf1fe00b;"
  "token_type": "bearer",
  "expires_in": 3599,
}

The contents of the output "access_token":"<bearer_access_token>" is your JWT. Insert the <bearer_access_token> value into the "Authorization: Bearer <bearer_access_token>" header when making requests to the API endpoint.

Windows NA Example


curl -X POST https://<tenant>.uaa.system.snakefly.dpsas.io/oauth/token -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=<insert_clientId>&client_secret=<insert_client_secret>"

Windows EU Example


curl -X POST https://<tenant>.uaa.system.pegasus.dpsas.io/oauth/token -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=<insert_clientId>&client_secret=<insert_client_secret>"

Windows Example Ouput


{"access_token":"<eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vc2FuZGJveC1jYS51YWEuc3l
zdGVtLnNuYWtlZmx5LmRwc2FzLmlvL3Rva2VuX2tleXMiLCJraWQiOiJzYW5kYm94LWNhLWtleTEiLCJ
0eXAiOiJKV1QifQ.eyJqdGkiOiJkNzVhMTkzMThlYTU0YjlhYTYzNGVhMTJiZjFmZTAwYiIsInN1YiI6
IjA3ZGJlNGViLTFkZjUtNGU5MC1iZjJhLWM4NTc1M2MxNTY5ZiIsImF1dGhvcml0aWVzIjpbImRwb2Qu
dHVpZC4yMmFhZmYxNi1iOTY5LTRjZTctODUxMC03ZDk0OTNhOTg0MmYiLCJkcG9kLnR1aWQuMjJhYWZm
MTYtYjk2OS00Y2U3LTg1MTAtN2Q5NDkzYTk4NDJmLnNndWlkLjMzODgyZWY1LTYyMzQtNGNiYy1hOWMx
LWM4YjczZjFlZmRhOCIsImRwb2QudGVuYW50LmFwaV9hcHBvd25lciJdLCJzY29wZSI6WyJkcG9kLnR1
aWQuMjJhYWZmMTYtYjk2OS00Y2U3LTg1MTAtN2Q5NDkzYTk4NDJmIiwiZHBvZC50ZW5hbnQuYXBpX2Fw
cG93bmVyIiwiZHBvZC50dWlkLjIyYWFmZjE2LWI5NjktNGNlNy04NTEwLTdkOTQ5M2E5ODQyZi5zZ3Vp
ZC4zMzg4MmVmNS02MjM0LTRjYmMtYTljMS1jOGI3M2YxZWZkYTgiXSwiY2xpZW50X2lkIjoiMDdkYmU0
ZWItMWRmNS00ZTkwLWJmMmEtYzg1NzUzYzE1NjlmIiwiY2lkIjoiMDdkYmU0ZWItMWRmNS00ZTkwLWJm
MmEtYzg1NzUzYzE1NjlmIiwiYXpwIjoiMDdkYmU0ZWItMWRmNS00ZTkwLWJmMmEtYzg1NzUzYzE1Njlm
IiwiZ3JhbnRfdHlwZSI6ImNsaWVudF9jcmVkZW50aWFscyIsInJldl9zaWciOiIzY2I3ODM3IiwiaWF0
IjoxNTk2ODI1NzU4LCJleHAiOjE1OTY4MjkzNTgsImlzcyI6Imh0dHBzOi8vc2FuZGJveC1jYS51YWEu
c3lzdGVtLnNuYWtlZmx5LmRwc2FzLmlvL29hdXRoL3Rva2VuIiwiemlkIjoiOWQ4MDYwY2ItNTg1OS00
YjI5LThlZGMtZTJiYTk5OGNmZDJhIiwiYXVkIjpbImRwb2QudHVpZC4yMmFhZmYxNi1iOTY5LTRjZTct
ODUxMC03ZDk0OTNhOTg0MmYuc2d1aWQiLCIwN2RiZTRlYi0xZGY1LTRlOTAtYmYyYS1jODU3NTNjMTU2
OWYiLCJkcG9kLnRlbmFudCIsImRwb2QudHVpZCJdfQ.Q2K2EJD82pbeiP3d5Hv_kpUR-M3-sbhNlAHre
j3rtXS0dWMOfZXqxY_CzfYbbpIUws2WskE6MOB_SbxkSoDEcGGQnfsleK4sXL2QFwVPmlUaQCOZSqjFP
K8qnKiS3DcUaCwL5AvVGyhm6yd1TQ-R68pXsosQbPJNfjX9VKD5APi_qZh5tHFOfkiVHfSXcZrh81DnT
xZoDlrly7886U8ADcKwCWIgH3WpyCaFS8QNtb2qucvsPZbBfES2AX_1e5rDgqQ5l01nQQnxLTQs0uBSu
UjLDKtQwCX6iyQ0ZbNaHodMwtVH7nQNL7MAot29bjZjjn4bzwEwppLpGLoc258LNg>","token_type":
"bearer","expires_in":3599,"scope":"dpod.tuid.22aaff16-b969-4ce7-8510-7d9493a984
2f dpod.tenant.api_appowner dpod.tuid.22aaff16-b969-4ce7-8510-7d9493a9842f.sguid
.33882ef5-6234-4cbc-a9c1-c8b73f1efda8","jti":"d75a19318ea54b9aa634ea12bf1fe00b"}

The contents of the output "access_token":"<bearer_access_token>" is your JWT. Insert the <bearer_access_token> value into the "Authorization: Bearer <bearer_access_token>" header when making requests to the API endpoint.

API Examples

Make requests to the tenant service endpoint. Provide the "access_token":"<bearer_access_token>", the output of Generating a JWT value in the "Authorization: Bearer <bearer_access_token>" header to authenticate requests. When executing requests using the JWT, requests must be sent to the URL/hostname - the URL available when you are logged in to the DPoD tenant platform.

Listing Tile Ids

Query the tile type list and return the available tiles. You can use the returned <tileId> to deploy a service through the API.

URL endpoint: /v1/tiles


https://<tenant>.<region>.market.dpondemand.io/v1/service_instances

Method: GET

Authorization: provide your JWT in the Authorization header.


Authorization: Bearer <bearer_access_token>

Linux Example


curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/tiles \
  -H "Authorization: Bearer $<bearer_access_token>"

Windows Example


curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/tiles -H "Authorization: Bearer <bearer_access_token>"

Example Output


{
    "number":0,
    "size":17,
    "totalElements":17,
    "totalPages":1,
    "content":[
        {
            "id":"<tileId>",
            "name":"<:tile_name>",
            "description":"<tile_description>",
            "shortCode":"<tile_shortcode>",
            "enabled": true,
            "serviceBrokerUrl": "serviceBrokerUrl",
            "helpURL": "Link to help and documentation",
            "categoryName": "Service Category",
            "imageUrl":
        }
    ]
}

The command returns the list of available tiles in the tenant. If there is a service you would like to use that is unavailable from the list of available tiles, contact your tenant administrator and request they enable the tile.

Creating a Service

Post a service request to deploy a service using the DPoD api. Use the <tileId> output from [Listing Tile IDs]{#listing-tile-ids}, to specify the type of service to be deployed. Alternatively, you can use the serviceType field to identify the tile by its shortcode.

Additional body entries are available in the DPoD API guide under Create a Service. This walkthrough only includes the essential entries.

URL Endpoint: /v1/service_instances


https://<tenant>.<region>.market.dpondemand.io/v1/service_instances

Method: POST

Authorization: provide your JWT in the Authorization header.


Authorization: Bearer <bearer_access_token>

Content-Type: application/json

Body: At minimum, you must provide a name for the service, and one of tileId or serviceType identifying the type of service to be deployed.


{
  "name": "<provide_name_for_service>",
  "tileId": "<tileId>"
}

Certain service types require additional parameters be provided in the request body. Refer to the DPoD API Guide for additional details.

Linux Example


curl -X POST https://<tenant>.<region>.market.dpondemand.io/v1/service_instances \
  -H "Authorization: Bearer $<bearer_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<provide_name_for_service>",
    "tileId": "<tileId>"
  }'

Windows Example


curl -X POST https://<tenant>.<region>.market.dpondemand.io/v1/service_instances -H "Authorization: Bearer < bearer_access_token>" -H "Content-Type: application/json" -d '{"name": "<provide_name_for_service>", "tileId": "<tileId>"}'

Listing Existing Services

Query the /v1/service_instances endpoint and return the quantity of existing services, the service id, the service name, and the service type. You require the output, the unique <serviceId>, to complete the Generating a Luna Cloud HSM Service Client operation.

You can query a specific service for its details. Maintain the same structure of the Listing existing services request, but add the <serviceId> to the URL endpoint: /v1/service_instances/<serviceId>.

URL endpoint: /v1/service_instances


https://<tenant>.<region>.market.dpondemand.io/v1/service_instances

Method: GET

Authorization: provide your JWT in the Authorization header.


Authorization: Bearer <bearer_access_token>

Linux Example


curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/service_instances \
  -H "Authorization: Bearer $<bearer_access_token>"

Windows Example


curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/service_instances -H "Authorization: Bearer <bearer_access_token>"

Generating a Luna Cloud HSM Service Client

Generate a set of client bindings to an existing Luna Cloud HSM Service. The command returns a set of credentials which can be used to access the service. The returned AuthTokenClientID and AuthTokenClientSecret can be used by an application owner to access the service.

Generating a Luna Cloud HSM Service Client requires access to the relevant <service_id_string> that you would like to generate the Luna Cloud HSM Service Client for. See Listing existing services for more information about acquiring the <service_id_string>.

API Request

URL endpoint: /v1/service_instances


https://<tenant>.<region>.market.dpondemand.io/v1/service_instances/<serviceId>/bindings

Method: PUT

Authorization: provide your JWT in the Authorization header.


Authorization: Bearer <bearer_access_token>

Content-Type: application/json

Body: Provide a name for the Luna Cloud HSM Service Client in the request body.


{
  "name":"<service_client_name>"
}

Linux Example


curl -X PUT  https://<tenant>.<region>.market.dpondemand.io/v1/service_instances/<serviceId>/bindings \
  -H "Authorization: Bearer $<bearer_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
   "name":"<service_client_name>"
  }' \

Windows Example


curl -X PUT  https://<tenant>.<region>.market.dpondemand.io/v1/service_instances/<serviceId>/bindings -H "Authorization: Bearer < bearer_access_token>" -H "Content-Type: application/json" -d '{"name":"<service_client_name>"}'

Deleting a Service

Delete a service from DPoD. Include the <serviceId> in the path when executing operations on a specific service. See Listing existing services for more information about acquiring the <serviceId>.

URL endpoint: /v1/service_instances/<serviceId>


https://<tenant>.<region>.market.dpondemand.io/v1/service_instances/<ServiceId>

Authorization: provide your JWT in the Authorization header.


Authorization: Bearer <bearer_access_token>

Examples

Linux Example


curl -X DELETE https://<tenant>.<region>.market.dpondemand.io/v1/service_instances/<serviceId> \
  -H "Authorization: Bearer $<bearer_access_token>"

Windows Example


curl -X DELETE https://<tenant>.<region>.market.dpondemand.io/v1/service_instances/<serviceId> -H "Authorization: Bearer <bearer_access_token>"