Software as a Service integration process

Last updated on May 7, 2026

This guide covers the technical interaction points required to connect your SaaS application with the STACKIT Marketplace. It details the customer journey from the initial subscription to final approval and ongoing access.

Prerequisites

Before starting the technical implementation, ensure the following technical requirements are met:

Vendor Project: You have set up your vendor project and successfully tested API access.
Product Data: Your product has been added to the STACKIT Marketplace central product database.
Sign-up URL: You have a publicly accessible landing page ready to receive customers redirected from STACKIT.

Integration paths for asynchronous vs. synchronous provisioning types

The implementation workflow depends on whether your product deployment is fully automated or requires manual intervention.

Synchronous delivery

Standard SaaS products are expected to be provisioned automatically. The STACKIT Marketplace expects an API-based approval shortly after the customer is redirected to your landing page.

Asynchronous delivery

SaaS async. is ideal for products that require manual configurations before the customer can gain access.

Manual Management: You can use a dedicated web UI in the STACKIT Marketplace “Subscription Management” area to manage orders manually.
Extended Timeouts: While standard subscriptions have a one-hour approval window, SaaS async. products allow for an approval window of up to 30 days.
Customer Communication: You will receive the customer’s email address to coordinate setup requirements during the manual implementation phase.

Technical implementation steps

To get your product live on the STACKIT Marketplace, you need to implement a secure handshake that transitions a customer from their subscription purchase to a fully activated account in your SaaS environment.

Handle the customer redirect
When a customer subscribes, STACKIT sends a GET request to your Sign-up URL. You must provide a public landing page that extracts the x-stackit-marketplace-token and prompts the user to create a local, independent account.
Verify the JWT
The token is an RS256 signed JWT. You need to download the public keys from STACKIT, verify the signature and expiration (5-minute TTL), and extract the subscriptionId from the payload.
Resolve the customer
Exchange the verified token for full subscription details by calling the /resolve-customer endpoint. This returns critical data, including the lifecycleState, productId, and the specific pricingPlan the customer selected.
Approve the subscription
Call the /approve endpoint to confirm the subscription is active on your side.

Handle the customer redirect

When a STACKIT customer subscribes to your product, they are redirected to your registered Sign-up URL via a GET request. This request includes a unique token used to identify the subscription.

Example request:

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

Landing page requirements

Public Access: The registration URL must be publicly accessible.
Identity Creation: You must collect all necessary user information during sign-up to create a new account on your side.
Identity Isolation: You cannot use STACKIT user identities. The customer must create a new, independent identity within your system.
Token Verification: You must verify the x-stackit-marketplace-token to ensure the request is authentic.

JWT verification

The x-stackit-marketplace-token is a short-lived JSON Web Token (JWT) signed with RS256. It contains the subscriptionId required for the next steps.

When the STACKIT Marketplace redirects to your SaaS application, it appends the x-stackit-marketplace-token parameter.

Header

The header contains metadata about the signature.

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

alg: The algorithm used to sign the token (RSA with SHA-256).
kid: The key ID used to identify the correct public key for verification.
typ: The token type, which is always JWT.

Body

The body contains the specific subscription identifier.

{
    "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, indicating where the public keys are available.
exp: The expiration timestamp (Unix epoch). The token is valid for 5 minutes after being issued.
iat: The “issued at” timestamp.

Verification steps

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 implementation examples, see the Python or Go reference code.

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.

Endpoint:

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

Request body:

{
  "token": "[token]"
}

Response body:

{
  "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.

Approve the subscription

Approving the subscription is the final step. This starts customer billing and confirms the service is active.

Critical Timing & Billing:

Standard TTL: For standard SaaS, pending subscriptions have a Time-to-Live (TTL) of one hour. If not approved within this window, the request fails.
Asynchronous TTL: For SaaS async. products, this window is extended up to 30 days.
Billing Trigger: Billing only begins once you successfully call the approval endpoint.