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 LockService.Ensure 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 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 SaaS API to enable subscription status and type checks.

Lock a subscription to a resourceLock a subscription to a resource

To lock a subscription 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/saas/v1/locks/ensure' \
  --header 'Authorization: Bearer <IAM_token>' \
  --header 'Content-Type: application/json' \
  --data '{
      "instanceToken": "<JWT>",
      "resourceId": "<resource_ID>"
  }'

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

As a result:

• Marketplace will link the subscription to the resource and return the link (Lock object).
• The SaaS product will save the link and start providing access to the resource.

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.

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