Using the APIs
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
The DPoD API documentation includes all publicly available endpoints. Endpoints scoped to user roles, dpod.tenant.*
, are for operations that are only accessible through the user interface. Endpoints scoped to API roles, dpod.tenant.api_*
, provide reduced permissions and are intended for application use.
All DPoD dpod.tenant.api_*
requests require an Oauth2 JSON Web Token (JWT) for authenticating over the API. DPoD Credentials are used to Generate a JWT.
The DPoD public APIs may include the following scopes:
dpod.tenant.spadmin
: Service Provider Administrator user role. Used to access the user interface.dpod.tenant.admin
: Tenant Administrator user role. Used to access the user interface.dpod.tenant.appowner
: Application Owner user role. Used to access the user interface.dpod.tenant.spadmin.unverified
: Unverified Service Provider Administrator temporary user role. Used to access the user interface during account verification.dpod.tenant.admin.unverified
: Unverified Tenant Administrator temporary user role. Used to access the user interface during account verification.dpod.tenant.appowner.unverified
: Unverified Application Owner temporary user role. Used to access the user interface during account verification.dpod.tenant.api_appowner
: Tenant Administrator and Application Owner API role. Used for application authentication over the API, the API role provides a subset of dpod.tenant.appowner and dpod.tenant.admin permissions to an application.dpod.tenant.api_service
: Service API role. Used for application authentication over the API, the API role provides a subset of dpod.tenant.appowner and dpod.tenant.admin permissions to an application.dpod.tenant.api_spadmin
: Service Provider Administrator API role. Used for application authentication over the API, the API role provides a subset of dpod.tenant.spadmin permissions to an application.
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.
Platform credentials are generated through the DPoD user interface. Platform credentials allow:
- Service Provider Administrators to access and manage tenants, users, and reports.
- Tenant Administrators and Application Owners to manage Luna Cloud HSM Services, Luna Cloud HSM Service Clients, service credentials, and subscriber groups.
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.
Warning
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.
Warning
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 are generated through the DPoD user interface. 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 refer to the relevant use case based API documentation.
Generate a set of platform credentials for authenticating to the DPoD API.
-
Select the Services tab and click on View Services (My Services for application owners). 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.
Warning
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 View Services (My Services for application owners). 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.
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
.
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 |
URL Endpoint | /oauth/token |
Method | POST |
Content-Type | application/x-www-form-urlencoded |
Body | grant_type=client_credentials client_id=<insert_clientId> client_secret=<client_secret> |
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.
URL Endpoint | /v1/tiles |
Method | GET |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
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":
}
]
}
List service plans and parameters
Query a tiles plans and return a list of the available service plans and the service parameters (createParams
). Use the tileId
output from List tile IDs to specify the service to be queried.
You must select a service plan and provide the required service parameters (createParams
) when provisioning a service over the API. For more information about provisioning a service over the API see Create Service.
URL Endpoint | /v1/tiles/{tileId}/plans |
Method | GET |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
Sample
curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/tiles/<tileId>/plans \
-H "Authorization: Bearer <bearer_access_token>"
curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/tiles/<tileId>/plans -H "Authorization: Bearer <bearer_access_token>"
Output
[
{
"id": "<Luna Cloud HSM Tile ID >",
"name": "single_hsm",
"description": "Standalone Luna SA",
"schemas": {
"service_instance": {
"create": {
"parameters": {
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [
"tenantId",
"serviceType",
"sguid"
],
"properties": {
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Billing account number used to charge the use of service."
},
"deviceType": {
"description": "Device type to be used for provisioning a partition.",
"default": "cryptovisor",
"type": "string",
"enum": [
"cryptovisor",
"cryptovisor_fips"
]
},
"serviceType": {
"type": "string",
"description": "The type of service."
},
"serviceVersion": {
"format": "string",
"description": "The version of the service (Default to 1.0.0)"
},
"sguid": {
"type": "string",
"format": "uuid",
"description": "The subscriber group id."
}
}
}
}
},
"service_binding": {
"create": {
"parameters": {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object"
}
}
}
}
}
]
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 the inclusion of additional parameters (createParams
) when creating a service over the API. For more information about listing required service parameters over the API see List Service Plans and Parameters
URL Endpoint | /v1/service_instances |
Method | POST |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
Content_Type | application/json |
Body | You must provide a service name , a servicePlan , a tileId or serviceType and any additional required createParams . For more information about required body contents see List Service Plans and Parameters. |
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 '{
"name": "<Luna Cloud HSM Service>",
"servicePlan": "single_hsm",
"tileId": "<tileId>",
"createParams": {
"deviceType: "cryptovisor_fips"
}
}'
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": "<Luna Cloud HSM Service>", "servicePlan": "single_hsm", "tileId": "<tileId>", "createParams": {"deviceType: "cryptovisor_fips"}}'
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.
Tip
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>
.
URL Endpoint | /v1/service_instances |
Method | GET |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
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>
.
URL Endpoint | /v1/service_instances/{service_id}/bindings |
Method | PUT |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
Content-Type | application/json |
Body | Provide a name for the Luna Cloud HSM Service Client in the request body.{"name":"<service_client_name>"} |
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>
.
URL Endpoint | /v1/service_instances/{service_id} |
Method | PUT |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
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.
Note
You require Platform Credentials to generate and retrieve an audit log file.
Caution
Filtering on the resource ID of a deleted service will fail. To access logs for a deleted service do not filter on the resource ID, instead generate a log file including all services.
Note
You cannot generate an audit log file larger than 1GB. If you are unable to generate an audit log file and are adhering to the maximum 31 day polling period, we recommend reducing the polling period, or filtering, to narrow the scope of your audit and generate smaller audit log files.
URL Endpoint | /v1/audit-log-exports |
Method | POST |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
Content-Type | application/json |
Body | You must provide a from value and a to value. The timestamp must be RFC3339 compliant, and you can query a period of up to 31 days.{ "from":"<audit_period_start_time>", "to":"<audit_period_end_time>" } You can filter the results by including any of the following: { "source":"<origin>", "resourceId":"<resourceID>", "actorId":"<actorID>", "action":"<action>", "status":"<status>" } See Common values and Use case specific values for more information about available values to filter by. |
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.
Tip
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 Logging - Downloading logs for more information about audit log values and format.
URL Endpoint | /v1/audit-log-exports/<jobId> |
Method | GET |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
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>"
}
Get subscriptions
Service provider administrators and tenant administrators can retrieve the subscription status and service data for services associated with the tenant. See the Subscription API for more information.
URL Endpoint | /v1/backoffice/subscriptions |
Method | GET |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
If you are using service provider platform credentials you must pass a tenantId as a query parameter at the end of the URL endpoint. Ex. /v1/backoffice/subscriptions?tenantID=<tenantId>
. If you are using tenant administrator platform credentials the subscriptions
endpoint will use your tenantId by default.
Sample
curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/backoffice/subscriptions \
-H "Authorization: Bearer <bearer_access_token>" \
curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/backoffice/subscriptions -H "Authorization: Bearer <bearer_access_token>" \
Output
[
{
"marketplaceName": "DPoD",
"serviceType": "cyberark_digital_vault",
"type": "TRIAL",
"state": "ACTIVE",
"autoRenewal": false,
"startDate": "2022-10-24",
"endDate": "2022-11-23",
"features": {}
},
{
"marketplaceName": "DPoD",
"serviceType": "key_vault",
"type": "PRODUCTION",
"state": "ACTIVE",
"autoRenewal": false,
"startDate": "2022-10-24",
"endDate": "2023-11-01",
"plan": "Luna Cloud HSM -Term Monthly Arrears with Overage",
"features": {
"quantity": 1
}
}
]
Get service agreements
Service provider administrators and tenant administrators can retrieve the service agreement details and status for a tenant. See the Subscription API for more information.
Service provider administrators can access the endpoint using the service provider platform credentials generated through the platform GUI, however tenant administrators must use the JWT generated on platform login.
URL Endpoint | /v1/backoffice/serviceAgreements/<tenantId> |
Method | GET |
Authorization | Authorization: Bearer <bearer_access_token> See Authorization for more information. |
Sample
curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/backoffice/serviceAgreements/<tenantId> \
-H "Authorization: Bearer <bearer_access_token>" \
curl -X GET https://<tenant>.<region>.market.dpondemand.io/v1/backoffice/serviceAgreements/<tenantId> -H "Authorization: Bearer <bearer_access_token>" \
Output
{
"terms": {
"duration": 12,
"mbus": [
{
"serviceType": {
"id": "a2c7f0e8-d9c3-462c-84b7-7b9e914c0d44",
"shortCode": "key_vault",
"name": "Luna Cloud HSM"
},
"quantity": 1
}
]
},
"submission": {
"submittedDate": "2022-10-24T18:13:26.989Z",
"tenantID": "<tenantId>",
"tenantName": "<tenantName>",
"tenantAdministrator": {
"userId": "<userId>",
"givenName": "<givenName>",
"familyName": "<familyName>",
"email": "<emailAddress>"
},
"parentAdministrator": {
"userId": "<userId>",
"givenName": "<givenName>",
"familyName": "<familyName>",
"email": "<emailAddress>"
}
},
"acceptance": {
"agreementDate": "2022-10-24T18:13:43.496Z",
"endOfAgreementDate": "2023-10-24T18:13:43.496Z",
"parentAdministrator": {
"userId": "<userId>",
"givenName": "<givenName>",
"familyName": "<familyName>",
"email": "<emailAddress>"
}
},
"cached": false
}