Getting started with the Marketplace License Manager API

In this section, you will learn how to integrate your product with the Yandex Cloud Marketplace License Manager API.

API interaction diagramAPI interaction diagram

On the diagram:

1. The application requests VM metadata. The metadata service address accessible from within the VM is used for this purpose.
2. In response, the application gets the id and vendor.folderId field values. These values ​​are used to get a list of links.
3. The application requests the Marketplace License Manager API for a list of links, providing the obtained resourceId and folderId field values ​​as parameters.
4. In response, the application gets an array of links, selects the required one, and uses it to activate some functionality.
5. From time to time, the application requests a confirmation of the link to the resource.
6. In response, the application gets the link confirmed and continues to operate.

Getting startedGetting started

To get started with the Marketplace License Manager API:

1. Become a partner of Marketplace and register a legal entity account.
2. In the partner dashboard, create a product and a service plan with the Subscription type.
3. Create a service account you will use to authenticate in the API.
4. Assign the service account the license-manager.saasSubscriptionSupervisor role for the partner profile and your product.
5. Get an IAM token for the service account you will use to authenticate in the License Manager API.

To use the examples, install cURL and gRPCurl (if using the gRPC API).

Set up integration with APISet up integration with API

To implement your product's business logic, update your app code by setting up integration with the License Manager API to enable subscription status and type checks.

Request the VM metadataRequest the VM metadata

1. Connect to the VM hosting your product.

2. In the VM terminal, run this command:

   curl \
     --header Metadata-Flavor:Google \
     169.254.169.254/computeMetadata/v1/instance/?recursive=true
   

   Where 169.254.169.254 is the address of the metadata service accessible from inside the VM.

   Result:

   {
     "attributes": {
       "install-unified-agent": "0",
       "serial-port-enable": "0",
       "ssh-keys": "user1:ssh-rsa ABC...",
       "user-data": "#cloud-config\ndatasource:\n Ec2:\n  strict_id: false\nssh_pwauth: no\nusers:\n- name: user1\n  sudo: ALL=(ALL) NOPASSWD:ALL\n  shell: /bin/bash\n  ssh_authorized_keys:\n  - ssh-rsa ABC..."
     },
     "description": "",
     "disks": [
       {
         "deviceName": "epdjv70ebov2********",
         "index": 0,
         "mode": "READ_WRITE",
         "type": "PERSISTENT"
       }
     ],
     "hostname": "compute-vm.ru-central1.internal",
     "id": "epdg9mn1pd9j********",
     "maintenanceEvent": "NONE",
     "name": "compute-vm",
     "networkInterfaces": [
       {
         "accessConfigs": [
           {
             "externalIp": "158.160.**.***",
             "type": "ONE_TO_ONE_NAT"
           }
         ],
         "forwardedIps": [],
         "ip": "10.12*.*.*",
         "mac": "d0:0d:10:4d:**:**",
         "network": "e2lb1da2dd9v********",
         "targetInstanceIps": []
       }
     ],
     "serviceAccounts": {},
     "tags": [],
     "vendor": {
       "cloudId": "b1gia87mbaom********",
       "environment": "ru-central1",
       "folderId": "b1g681qpemb4********",
       "identity": {
         "base64": "VPb...",
         "document": "{\"instanceId\":\"epdg9mn1pd9j********\",\"productCodes\":null,\"imageId\":\"fd8hp9las7k4********\",\"productIds\":[\"f2egeq0c2kd6********\"],\"createdAt\":\"2024-11-13T13:33:42Z\",\"version\":\"2023-03-01\"}",
         "dsa": "-----BEGIN PKCS7-----\nMI...\n-----END PKCS7-----\n",
         "rsa": "-----BEGIN PKCS7-----\nMI...-----END PKCS7-----\n"
       },
       "labels": {}
     },
     "virtualClock": {
       "driftToken": 0
     },
     "zone": "projects/b1g681qpemb4********/zones/ru-central1-b"
   }
   

   Save the values of the id and vendor.folderId fields. You will need them to request a list of links.

Get a list of linksGet a list of links

To get a list of links of subscriptions to resources, use the List REST API method for the Lock resource or the LockService/List gRPC API call.

curl \
  --request GET \
  --url 'https://marketplace.api.cloud.yandex.net/marketplace/license-manager/v1/locks?folderId=<folder_ID>&resourceId=<resource_ID>' \
  --header 'Authorization: Bearer <IAM_token>' \
  --header 'Content-Type: application/json'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{
      "folderId": "<folder_ID>",
      "resourceId": "<resource_ID>"
  }' \
  marketplace.api.cloud.yandex.net:443 yandex.cloud.marketplace.licensemanager.v1.LockService/List

Result:

{
  "locks": [
    {
      "id": "enp0asmd9pr9********",
      "instanceId": "epdg9mn1pd9j********",
      "resourceId": "epdg9mn1pd9j********",
      "startTime": "2024-01-01T12:34:56.123456789Z",
      "endTime": "2024-01-01T13:34:56.123456789Z",
      "createdAt": "2024-01-01T12:34:56.123456789Z",
      "state": "LOCKED",
      "templateId": "enpbhhpl3vs5********"
    }
  ]
} 

Save the values of the instanceId and resourceId fields. You will need them to link your subscription to the resource.

Request a link to the resourceRequest a link to the resource

To link a subscription to a resource and to make sure it is linked to a resource, use the Ensure REST API method for the Lock resource or the LockService/Ensure gRPC API call.

curl \
  --request POST \
  --url 'https://marketplace.api.cloud.yandex.net/marketplace/license-manager/v1/locks/<instance_ID>:ensure' \
  --header 'Authorization: Bearer <IAM_token>' \
  --header 'Content-Type: application/json' \
  --data '{
      "resourceId": "<resource_ID>"
  }'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{
      "instanceId": "<instance_ID>",
      "resourceId": "<resource_ID>"
  }' \
  marketplace.api.cloud.yandex.net:443 yandex.cloud.marketplace.licensemanager.v1.LockService/Ensure

Result:

{
  "id": "e2371l9d5u8a********",
  "description": "lock ensured",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.marketplace.licensemanager.v1.EnsureLockMetadata",
    "lockId": "enp0asmd9pr9********"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.marketplace.licensemanager.v1.Lock",
    "id": "enp0asmd9pr9********",
    "instanceId": "epdg9mn1pd9j********",
    "resourceId": "epdg9mn1pd9j********",
    "startTime": "2024-01-01T12:34:56.123456789Z",
    "endTime": "2024-01-01T13:34:56.123456789Z",
    "createdAt": "2024-01-01T12:34:56.123456789Z",
    "state": "LOCKED",
    "templateId": "enpbhhpl3vs5********"
  }
}

As a result, the service will link the subscription to the resource. If the subscription is already linked, the service will simply confirm the link.