This guide provides an introduction to using the Thales Data Protection on Demand APIs. It provides guidelines for authenticating and example commands for common DPoD API requests. DPoD provides multiple APIs, refer to the appropriate DPoD API for more information about available endpoints, parameters and requests.

Authorization

All DPoD API requests require an Oauth2 JSON Web Token (JWT) for authorization. DPoD Credentials are used to Generate a JWT. The JWT is required for authenticating requests over the API.

Credentials

Platform or service credentials are a clientId and clientSecret generated through the DPoD user interface. Endpoint availability is limited to the scope of your credentials.

Generate a JWT

To generate a JWT you authenticate to your tenant log in URL Oauth2 endpoint using the Credentials clientId and clientSecret. This endpoint implements an OAuth2 client credentials grant, returning a JWT in the response body. The JWT takes the format "access_token":"<bearer_access_token>". Insert the <bearer_access_token> value into the "Authorization: Bearer <bearer_access_token>" header when making requests to the API endpoint. The JWT expires after 1 hour. If the JWT expires, you need to generate a new JWT to continue executing commands over the API.

To determine your authentication domain, access your DPoD tenant log in screen and copy the URL. Remove /login and append /oauth/token.

Examples

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>"

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>"

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>"

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>"

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 to authenticate requests to the API endpoint.

Example requests

API requests are made to the tenant URL/hostname endpoint. Use the "<bearer_access_token>" value, the output of Generating a JWT, in the "Authorization: Bearer <bearer_access_token>" header to authenticate requests to the API endpoint.

List tile IDs

Query the tile list and return the available tiles for the tenant. 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.

Sample

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

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

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":
        }
    ]
}

Create service

Post a service request to deploy a service using the DPoD api. Use the <tileId> output from List 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.

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

Sample

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

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

List provisioned 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 can query a specific service for its details. Maintain the same structure of the List provisioned services request, but add the <serviceId> to the URL endpoint: /v1/service_instances/<serviceId>.

Sample

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

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

Generate 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 List provisioned services for more information about acquiring the <service_id_string>.

Sample

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>"
}' \

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>"}'

Delete service

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

Sample

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

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

Generate Audit Log File

Generate an audit log file for Luna Cloud HSM Services. The command returns a jobId which can be used to retrieve the generated audit log file as described in Retrieve Audit Log File.

You require Platform Credentials to generate and retrieve an audit log file.

The limit for an individual audit log query is 1GB. If the query results in an audit log file which exceeds 1GB the request will fail and you will have to refine the query.

Sample

curl -X POST https://<tenant>.<region>.market.dpondemand.io/v1/audit-log-exports \
-H "Authorization: Bearer <bearer_access_token>" \
-H "Content-Type: application/json" \
-d '{
    "from":"2022-03-14T00:00:00Z",
    "to":"2022-03-14T16:00:00Z"
}'

curl -X POST https://<tenant>.<region>.market.dpondemand.io/v1/audit-log-exports -H "Authorization: Bearer <bearer_access_token>" -H "Content-Type: application/json" -d '{"from":"2022-03-14T00:00:00Z",     "to":"2022-03-14T16:00:00Z"}'

Output

{
    "jobId": "<jobId>",
    "startedAt": "<jobStartTime>",
    "endedAt": "<jobEndTime,
    "state": "ACTIVE",
    "location": null
}

Retrieve Audit Log File

Retrieve the audit log file from a Generate Audit Log File request. Include the jobId, returned by the Generate Audit Log File request, in the path when retrieving an audit log file.

You require Platform Credentials to generate and retrieve an audit log file.

The request returns a signed URL that you can access to download the audit log file. The signed URL expires after 24 hours. The audit log file is a .ZIP file that contains a JSON list of audit logs. See Audit Logs for more information about the the audit log values and format.

Sample

curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/audit-log-exports/<jobId> \
-H "Authorization: Bearer <bearer_access_token>" \

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

Output

{
    "jobId": "<jobId>",
    "startedAt": "<jobStartTime>",
    "endedAt": "<jobEndTime>",
    "state": "SUCCEEDED",
    "location": "<signedUrl>"
}