Getting started with the Marketplace License Manager SaaS API

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

API interaction diagramAPI interaction diagram

On the diagram:

1. The user purchases a subscription to a SaaS product in Marketplace.
2. Marketplace sends a link to the SaaS product to the user. The token URL parameter in the link contains a JWT.
   The link address is specified in the Link to landing page field when creating the product version in Marketplace.
3. Once the user follows the link, the SaaS product gets a JWT.
4. Authentication option 1: the user already has an account with the SaaS product. In which case they enter their credentials and log in.
5. Authentication option 2: the user has no account with the SaaS product. In which case they create a new account and log in.
6. The SaaS product sends the ProductInstanceService.Claim request to Marketplace. That request contains the token it got from the user and the SaaS product's resource ID.
7. As a result, Marketplace links the subscription to the resource and returns the link (Lock object) to the SaaS product.
8. The SaaS product saves the link and starts providing access to the resource.
9. The SaaS product inquires Marketplace for the link every once in a while.
10. Marketplace returns the link to the SaaS product for as long as the subscription is active.

Getting startedGetting started

To get started with the Marketplace License Manager SaaS API:

1. Become a partner of Marketplace and register a legal entity account.
2. In the partner dashboard, create a Subscription type product and service plan.
3. Create a service account you will use to authenticate in the API.
4. Assign to the service account the license-manager.saasSubscriptionSupervisor and marketplace.productInstances.saasSupervisor roles for the partner profile or an individual 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 the product's business logic, refine your app code yourself by setting up integration with the License Manager SaaS API and Product Instance Manager API to enable subscription status and type checks:

1. Authenticate to the License Manager API and Product Instance Manager API as a service account. For authentication, use an IAM token.

2. Create a page to redirect the user to when linking their purchased subscription to the service. This page is where the user has to authenticate.

   When the user gets redirected to such a page, a JWT token (token) generated by Yandex Cloud is provided in the token parameter in the request string. The JWT token is valid for 15 minutes and contains the following:

   • ID of the subscription purchased by the user (license_instance_id).
   • ID of the subscription template you created in the partner dashboard (license_template_id).
   • ID of the user's activated product instance (product_instance_id).

3. While the JWT is valid, use the new page to authenticate the user and save the unique ID assigned to the activated product instance (product_instance_id).

4. Link this unique product instance ID (product_instance_id) to the subscription purchased by the user (license_instance_id).

   You can link the ID to the subscription using the Claim REST API method for the ProductInstance resource or the ProductService/Claim gRPC API call.

   Provide the following in the request:

   • JWT (token).
   • Optionally, unique user ID in your system (resource_id).
   • Optionally, additional metadata (resource_info).

   In response, you will get the link ID (lock_id) in the metadata parameter. If the response returns an error, the subscription failed to link to the service and you need to ask the user to complete all the steps again.

5. Make sure to regularly check your subscription link is active. To do this, use the link ID (lock_id) you got in the previous step.

   To get up-to-date information about a linked subscription, use one of these:

   • The get REST API method for the Lock resource or LockService/Get gRPC API call.

     The response must return the active Lock resource with state = LOCKED and the subscription expiry time (end_time) set to a future value.

   • The getByResourceID REST API method for the Lock resource or LockService/Get gRPC API call.

     A successful response must return the active Lock resource, otherwise the NOT_FOUND error.

   Note

   Note that the user can unlink a subscription from the service and link a different one. Make sure your code can handle cases like this correctly.

6. Implement business logic to process subscriptions: consumption records, limitations related to time, number of users, etc.

Get information about a linkGet information about a link

To get information about a link, use the Get REST API method for the Lock resource or the LockService/get gRPC API call:

curl \
  --request GET \
  --url 'https://marketplace.api.cloud.yandex.net/marketplace/license-manager/saas/v1/locks/<link_ID>' \
  --header 'Authorization: Bearer <IAM_token>' \
  --header 'Content-Type: application/json'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{
      "lockId": "<link_ID>"
  }' \
  marketplace.api.cloud.yandex.net:443 yandex.cloud.marketplace.licensemanager.saas.v1.LockService/Get

As the result, Marketplace will return the link (Lock object) if the subscription is active and linked to the user's product instance.

Track subscription renewalTrack subscription renewal

To track subscription renewal, you should monitor the changes of the end_time field value in the subscription instance.

To get the subscription instance info, use the Get REST API method for the Instance resource or the InstanceService/Get gRPC API call:

curl \
  --request GET \
  --url 'https://marketplace.api.cloud.yandex.net/marketplace/license-manager/saas/v1/instances/<instance_ID>' \
  --header 'Authorization: Bearer <IAM_token>'

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d '{
      "instanceId": "<instance_ID>"
  }' \
marketplace.api.cloud.yandex.net:443 yandex.cloud.marketplace.licensemanager.saas.v1.InstanceService/Get