[Yandex Cloud documentation](../../../../index.md) > [Yandex Cloud Marketplace](../../../index.md) > Partners > License Manager SaaS API reference > Getting started with the License Manager SaaS API

# Getting started with the Marketplace License Manager SaaS API

In this section, you will learn how to integrate your SaaS [product](../../../concepts/product.md) with the Yandex Cloud Marketplace License Manager SaaS API.

## API interaction diagram {#visualization}


![api-saas-interaction-diagram](../../../../_assets/marketplace/api-saas-interaction-diagram.svg)

On the diagram:

1. The user purchases a subscription to a SaaS product in Marketplace.
1. 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](../../../operations/create-new-version.md) the product version in Marketplace.
1. Once the user follows the link, the SaaS product gets a JWT.
1. _Authentication option 1_: the user already has an account with the SaaS product. In which case they enter their credentials and log in.
1. _Authentication option 2_: the user has no account with the SaaS product. In which case they create a new account and log in.
1. 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.
1. As a result, Marketplace links the subscription to the resource and returns the link (`Lock` object) to the SaaS product.
1. The SaaS product saves the link and starts providing access to the resource.
1. The SaaS product [inquires](#get-lock) Marketplace for the link every once in a while.
1. Marketplace returns the link to the SaaS product for as long as the subscription is active.

## Getting started {#before-you-begin}

To get started with the Marketplace License Manager SaaS API:

1. [Submit an application](../../../quickstart.md#send-application) and [register](../../../operations/registration.md) a legal entity account.

1. In the Yandex Cloud UI:
    1. [Create](../../../../iam/operations/sa/create.md) a service account you will use to authenticate in the License Manager SaaS API.
    1. [Get an IAM token](../../../../iam/concepts/authorization/iam-token.md) for your service account.

1. In the Marketplace [partner dashboard](https://partners.yandex.cloud/):
    1. Create a [Subscription](../../../concepts/subscription.md) type [product](../../../operations/create-product.md) and [service plan](../../../operations/create-tariff.md).
    1. [Assign](../../../security/partners.md#assign-role) to the service account the `license-manager.saasSubscriptionSupervisor` and `marketplace.productInstances.saasSupervisor` roles for the [partner profile](../../../concepts/publisher.md) or an individual [product](../../../concepts/product.md).

To use the examples, install [cURL](https://curl.haxx.se) and [gRPCurl](https://github.com/fullstorydev/grpcurl) (if using the [gRPC API](grpc/index.md)).


## Set up integration with API {#integrate}

To implement the product's business logic, refine your app code yourself by [setting up integration](../../../operations/license-manager-integration.md) 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](../../../../iam/concepts/authorization/iam-token.md).
1. 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`).

1. 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`).
1. 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](../../../pim/saas/api-ref/ProductInstance/claim.md) REST API method for the [ProductInstance](../../../pim/saas/api-ref/ProductInstance/index.md) resource or the [ProductService/Claim](../../../pim/saas/api-ref/grpc/ProductInstance/claim.md) 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.

1. 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](Lock/get.md) REST API method for the [Lock](Lock/index.md) resource or [LockService/Get](grpc/Lock/get.md) 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](Lock/getByResourceID.md) REST API method for the [Lock](Lock/index.md) resource or [LockService/Get](grpc/Lock/getByResourceID.md) gRPC API call.

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

    {% note info %}

    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.

    {% endnote %}

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


### Get information about a link {#get-lock}

To get information about a link, use the [Get](Lock/get.md) REST API method for the [Lock](Lock/index.md) resource or the [LockService/get](grpc/Lock/get.md) gRPC API call:

{% list tabs group=instructions %}

- REST API {#api}

  ```bash
  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'
  ```

  Where `<link_ID>` is the `lockId` field value.

- gRPC API {#grpc-api}

  ```bash
  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
  ```

  Where `lockId` is the `lockId` field value obtained at the previous step.

{% endlist %}

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 renewal {#track-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](Instance/get.md) REST API method for the [Instance](Instance/index.md) resource or the [InstanceService/Get](grpc/Instance/get.md) gRPC API call:

{% list tabs group=instructions %}

- REST API {#api}

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

  Where `<instance_ID>` is the subscription instance ID.

- gRPC API {#grpc-api}

  ```bash
  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
  ```

  Where `instanceId` is the subscription instance ID.

{% endlist %}