Integration process

The SaaS product integration should cover the following points:

The vendor provides a signup URL where a STACKIT customer can register and onboard to the product.
The vendor can also provide a login or instance URL for the customer to use the product after they subscribe.
The vendor triggers requests, for example, by approving pending subscription requests.
A STACKIT Marketplace customer triggers requests, for example, by subscribing to a SaaS product.
The state within the STACKIT Marketplace changes, for example, when the subscription’s validity period ends.

If your SaaS product doesn’t have a web UI, please contact the STACKIT Marketplace team at marketplace@stackit.cloud.

The product information sheet is the starting point for becoming a STACKIT Marketplace provider and for the integration process. You can specify the redirect URLs in this sheet. You can provide the instance URL dynamically when a subscription is approved. The STACKIT Marketplace team will give you the template.

Prerequisites

Before you begin, make sure you have done the following:

You’ve set up your vendor project and successfully tested the API access. For more information, see: Setting up your vendor project.
Your product has been added to the STACKIT Marketplace product master data. The STACKIT Marketplace team will help you with this step.

Common Scenarios

1. A customer subscribes to a SaaS product

When a STACKIT customer subscribes to a product on the STACKIT Marketplace, they are redirected to the SaaS signup URL. This is done through a GET request that includes an x-stackit-marketplace-token parameter. A subscription object is created to record the purchase.

The vendor API must approve the subscription to start customer billing. Pending subscriptions have a Time-to-Live (TTL) of one hour. If this time is exceeded, the subscription status changes to SUBSCRIPTION_REJECTED, which means the request failed.

Example:

GET https://marketplace-app.eu/register?x-stackit–marketplace-token=[token]

Landing page requirements

The landing page must meet these requirements:

The registration URL must be publicly accessible and can be opened by STACKIT Marketplace customers.
You should get all required user information during signup and onboarding to enable the SaaS product’s functionality.
The customer must create a new identity and account on the SaaS product side. You cannot use the STACKIT user identity or federation. The STACKIT Marketplace never shares a user’s personal information.
If necessary, customize the customer onboarding process to improve the customer experience. This may include a specific landing page for STACKIT Marketplace customers.
The x-stackit-marketplace-token shows that the user was redirected from the STACKIT Marketplace platform. You must check the value of the token (JWT) to ensure it’s authentic and hasn’t been tampered with. See “JWT verification” below.

STACKIT Marketplace token

When the STACKIT Marketplace redirects to your SaaS application, it appends an x-stackit-marketplace-token parameter. The token value is a short-lived JSON Web Token (JWT) that contains the vendor’s subscription ID. The JWT is signed with RS256 (RSA with SHA-256).

JWT user data

Header

{
    "alg": "RS256",
    "kid": "uuid",
   "typ": "JWT"
}

alg: Specifies the algorithm used to sign the token (RSA with SHA-256). This field will always have this value.
kid: The key ID used to get the key to sign the token. This is useful for key rotation scenarios.
type: Specifies the token type. This field will always have this value.

Payload

{
    "subscriptionId": "uuid",
    "iss": "https://keys.marketplace.stackit.cloud/v1/resolve-customer/keys.json",
  "exp": 1683081000,
    "iat": 1683077400
}

subscriptionId: The unique identifier for the vendor’s subscription.
iss: The issuer claim, which indicates where the public key(s) for verifying the token are publicly available.
exp: The expiration field is a timestamp (in seconds since the Unix epoch) indicating when the token expires. It’s always 5 minutes after the issued at timestamp.
iat: The issued at field is a timestamp indicating when the token was created.

JWT verification

The x-stackit-marketplace-token indicates that the user was redirected from the STACKIT Marketplace. You need to verify the JWT’s value to ensure its authenticity and integrity and to prevent tampering.

Download the STACKIT Marketplace public keys: https://keys.marketplace.stackit.cloud/v1/resolve-customer/keys.json.
Decode the JWT and read the key ID from the header.
Use the key ID to choose the correct public key from the keys you downloaded.
Verify the JWT signature using the public keys from the STACKIT Marketplace.
Ensure the JWT hasn’t expired.
Check that the issuer matches the STACKIT Marketplace issuer.
Ensure the subscription ID matches the subscription ID returned by the Resolve Customer flow.

For an example of how to technically implement this process, check out the Python or Go examples in the STACKIT Marketplace code examples repository.

2. Resolve customer

The STACKIT Marketplace redirects the customer to the registered SaaS landing page and adds an x-stackit-marketplace-token. The token value is a five-minute JSON Web Token (JWT) that contains the vendor’s subscription ID. This token can be exchanged for subscription information through the vendor API.

POST /v1/vendors/projects/[projectId]/resolve-customer

User data of the request, where [Token] is the token:

{
    "token": "[token]"
}

Answer-Payload:

{
  "lifecycleState": "SUBSCRIPTION_PENDING",
  "product": {
    "deliveryMethod": "SAAS",
    "lifecycleState": "PRODUCT_LIVE",
    "priceType": "CONTRACT",
    "pricingPlan": "Test Plan",
    "productId": "2ea4b536-07c8-479e-a7a7-41ff724e053f",
    "productName": "Test Product Name",
    "vendorName": "STACKIT",
    "vendorPlanId": "custom-plan-id-123", // vendor-provided identifier; optional
    "vendorProductId": "vendor-custom-id", // vendor-provided identifier; optional
    "vendorWebsiteUrl": "https://example.com"
  },
  "projectId": "c5fedcab-920d-40cd-a06f-e7443db8e7f7",
  "subscriptionId": "e93750b2-3d5c-496e-844d-67c947e34c67"
}

Check out the Go and Python sections in the STACKIT Marketplace code examples repository for examples.

3. Approve subscription

You should approve the subscription if the following conditions are met:

The customer has successfully registered on the SaaS product site and has been added to the system. This includes a successful customer login and the persistence of the STACKIT Marketplace mapping identifiers, such as the vendor’s subscription ID.
The SaaS product is fully provisioned and the SaaS user can use it.

POST /v1/vendors/projects/{projectId}/subscriptions/{subscriptionId}/approve

For examples of what an implementation with the Golang or Python STACKIT SDKs might look like, check out the Go and Python sections in the STACKIT Marketplace code examples repository.

If you encounter errors during customer registration or onboarding that make the SaaS product unusable, you must not approve the subscription request. Please open a STACKIT Support ticket or contact the STACKIT Marketplace team immediately for help at marketplace@stackit.cloud.

When a customer has an active product subscription, the STACKIT Marketplace can redirect them to a login page for the SaaS product with a GET request. No x-stackit-marketplace-token parameter is appended.

If you don’t specify a login URL, the registration URL is used (without the x-stackit-marketplace-token parameter).
The STACKIT Marketplace supports a unique login URL for each subscription. This URL can point to a specific customer app instance. Please specify the login URL in the Approve Subscription request.

STACKIT Marketplace status changes

The subscription status on the provider side must be synchronized with the status on the STACKIT Marketplace. This includes new subscriptions, terminations, and updates. You should implement a polling mechanism with an appropriate frequency to get the current status of subscriptions.

When subscriptions are created or deleted, you can be notified automatically via email so you can take action and plan changes. Contact the STACKIT Marketplace team for help with this.