Health Exposure Service API

This is an information message

Advanced usage

When managing this service in the ESC Portal, the same API is used. The difference is that the portal automates (and hence hides) some steps in order to increase usability. Using the API directly requires extra steps to be done manually. See the Certificate Lifecycle Workflow below.

Endpoint

The HES API is exposed under the endpoint https://hes.entcloud.swisscom.com/api/v1. The paths in this API must be appended to the endpoint path.

Common Values

In the API description below, the following values are repeatedly used either as request parameters or in responses, and hence described here for simplicity:

Value	Type	Description
business-group-id	string	The UUID of the business group associated with the service instance
business-group-name	string	The name of the business group associated with the service instance
created-by	string	Represents the API user that created the service instance user
creation-date	string	The creation date of the user certificate
expiration-date	string	The expiration date of the user certificate
instance-id	string	The UUID of the service instance
instance-name	string	The name of the service instance
instance-status	string	The status of the service instance. One of: IN PROGRESS, READY
user-certificate	string	The certificate of the service instance user
user-consumer-group	string	The consumer group a service instance user is part of
user-contact-email	string	The email address of the contact to notify when the user certificate approaches expiration
user-csr	string	The Base64-encoded certificate signing request used to generate the user certificate
user-description	string	The description of the service instance user
user-id	string	The UUID of the service instance user
user-name	string	The name of the service instance user
user-status	string	The status of the service instance user. One of: IN PROGRESS, READY

This is an information message

Please Note

Some operations require the business-group-id and business-group-name fields. These are needed for the future development of this service and are currently not used. The ESC Portal sets them to the values corresponding to the default business group of the tenant (i.e. the business group sharing the same name with the tenant).

REST API

GET

/tenants/{{tenant}}/instances — Lists all service instances for a tenant

Lists all service instances for a tenant.

This is an information message

Please Note

In the current implementation, there can be zero or one service instances per tenant.

curl --location --request GET '/tenants/{{tenant}}/instances' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{token}}'

{
  "items": [
    {
      "businessGroupId": "{{business-group-id}}",
      "businessGroupName": "{{business-group-name}}",
      "id": "{{instance-id}}",
      "name": "{{instance-name}}",
      "status": "{{instance-status}}"
    }
  ]
}

POST

/tenants/{{tenant}}/instances — Creates a service instance

Creates a service instance

curl --location --request POST '/tenants/{{tenant}}/instances' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{token}}' \
  --data '{{request-payload}}'

{
  "businessGroupId": "{{business-group-id}}",
  "businessGroupName": "{{business-group-name}}"
}

{
  "id": "{{instance-id}}",
  "name": "{{instance-name}}",
}

GET

/tenants/{{tenant}}/instances/{{instance-id}} — Returns info about the service instance

Returns info about the service instance

curl --location --request GET '/tenants/{{tenant}}/instances/{{instance-id}}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{token}}'

{
  "businessGroupId": "{{business-group-id}}",
  "businessGroupName": "{{business-group-name}}",
  "id": "{{service-instance-id}}",
  "name": "{{service-instance-name}}",
  "status": "{{service-instance-status}}"
}

GET

/tenants/{{tenant}}/instances/{{instance-id}}/users — Lists all users for a service instance

Lists all users for a service instance. There can be zero or more users per service instance.

curl --location --request GET '/tenants/{{tenant}}/instances/{{instance-id}}/users' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{token}}'

{
  "items": [
    {
      "businessGroupId": "{{business-group-id}}",
      "businessGroupName": "{{business-group-name}}",
      "consumerGroup": "{{user-consumer-group}}",
      "contact": {
        "email": "{{user-contact-email}}"
      },
      "createdBy": "{{created-by}}",
      "creationDate": "{{creation-date}}",
      "expirationDate": "{{expiration-date}}",
      "id": "{{user-id}}",
      "name": "{{user-name}}",
      "description": "{{user-description}}",
      "status": "{{user-status}}"
    }
  ]
}

POST

/tenants/{{tenant}}/instances/{{instance-id}}/users — Creates a new service instance user

Creates a new service instance user

curl --location --request POST '/tenants/{{tenant}}/instances/{{instance-id}}/users' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{token}}' \
  --data '{{request-payload}}'

{
  "businessGroupId": "{{business-group-id}}",
  "businessGroupName": "{{business-group-name}}",
  "consumerGroup": "{{user-consumer-group}}",
  "contact": {
    "email": "{{user-contact-email}}"
  },
  "csr": "{{user-csr}}",
  "description": "{{user-description}}"
}

{
  "id": "{{user-id}}",
  "name": "{{user-name}}"
}

GET

/tenants/{tenant}/instances/{instance-id}/users/{{user-id}} — Deletes the service instance user

Deletes the service instance user

curl --location --request GET '/tenants/{tenant}/instances/{instance-id}/users/{{user-id}}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{token}}'

GET

/tenants/{{tenant}}/instances/{{instance-id}}/users/{{user-id}} — Returns details about a service instance user

Returns details about a service instance user

curl --location --request GET '/tenants/{{tenant}}/instances/{{instance-id}}/users/{{user-id}}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{token}}'

{
  "businessGroupId": "{{business-group-id}}",
  "businessGroupName": "{{business-group-name}}",
  "consumerGroup": "{{user-consumer-group}}",
  "contact": {
    "email": "{{user-contact-email}}"
  },
  "createdBy": "{{created-by}}",
  "creationDate": "{{creation-date}}",
  "expirationDate": "{{expiration-date}}",
  "id": "{{user-id}}",
  "name": "{{user-name}}",
  "certificate": "{{user-certificate}}",
  "description": "{{user-description}}",
  "status": "{{user-status}}"
}

Certificate Lifecycle Workflow

The workflow for managing certificates is as follows:

• Obtain an authorization token (see the Auth documentation for more details). This needs to be provided with each of the following requests.
• Check if your tenant is onboarded: GET /tenants/{{tenant}}/instances
• Onboard the service for your tenant if not done already: POST /tenants/{{tenant}}/instances
• Create a new user: POST /tenants/{{tenant}}/instances/{{instance-id}}/users
• List all existing users: GET /tenants/{{tenant}}/instances/{{instance-id}}/users
• Get certificate for a user: GET /tenants/{{tenant}}/instances/{{instance-id}}/users/{{user-id}}
• Delete a user certificate: DELETE /tenants/{{tenant}}/instances/{{instance-id}}/users/{{user-id}}