Creating Connect Sessions

Prerequisites

In order to use Connect Sessions, you will need:

Creating a Connect Session

To create a connect session, send a POST request to the /connectSessions endpoint. A request to create a Connect Session could look like this:

Creating a Connect Session with checkoutNewSubscription intent

curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/connectSessions" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --data '{
    "callbackUrl": "https://example.com",
    "intent": {
      "type": "checkoutNewSubscription",
      "checkoutNewSubscription": {
        "plan": "pln_0U32ZjA60Z7P8Y5vLtmvXaIMEiPr"
      }
    },
    "user": "usr_0U2ViuFW0Z7P8Y2S1L76mfADMT6m"
  }'

This will create an authenticated Connect Session with the intent to checkout a new subscription for the given plan and user:

JSON response of checkoutNewSubscription Connect Session

{
  "object": "connectSession",
  "id": "csn_0U2UMLEo0Z7P8Y37BOdNohpMnq0Y",
  "callbackUrl": "<https://example.com>",
  "intent": {
    "type": "checkoutNewSubscription",
    "checkoutNewSubscription": { "plan": "pln_0U2qJyIT0Z7P8Y1M6uFNjOiO5sws" }
  },
  "url": "<https://connect.gigs.com/checkout/entry?session=csn_0SNlurA049MEWV1GWxpaE5D0t2D7&token=lzODbEyaUQjVRAmalD4pdaq5Nkn1Lw0qTL6Rdsh7PwLVES6N7ImWxnCYbJA99AXp>",
  "user": "usr_0SNlurA049MEWV1BAAmWZULA4tm8"
}

You can now redirect your user to the url provided in the response, which will launch Connect. As this is an authenticated Connect Session, the user will bypass the Connect login flow and directly enter the checkout process with the given plan selected.

Best practices

When using Connect Session, we recommend to stick to the following best practices:

  • Make sure to use a created Connect Session as soon as possible Connect Sessions have a limited lifetime, so you should use the session as soon as possible after creation to prevent errors.
  • Start Connect Sessions just before they're needed. Following the previous advice, it's best to create Connect Sessions only when you're about to use them.
  • Do not store or expose the url field. For authenticated sessions, this field has an encrypted session token attached to it. It can be used to log in as the user and should be treated like a password. Do not store or expose it in any way.
  • Avoid updating Connect Sessions when possible. Although there is a PATCH endpoint available for modifying Connect Sessions, note that the url field is generated only when a Connect Session is first created or when it is updated with user information. Changing other details, like the callbackUrl, will result in the url field being empty in the response. This aligns with the recommendation against saving the url. Therefore, try not to change a Connect Session once it's created. If you find yourself needing to update it, it might indicate that it was created too early in your process.

Using Connect Sessions with Native Apps

When integrating Connect Sessions into native mobile applications, there are some important considerations to keep in mind:

  • Use a native webview. For the most stable experience, we recommend opening Connect Sessions in a native webview component (such as WKWebView on iOS or WebView on Android).
  • Connect cannot be embedded as an iFrame. Due to security restrictions, Connect & Connect Sessions cannot be embedded within iFrames. Always load them in a full webview or browser context.
  • Let Connect handle the user flow. Once a Connect Session is launched, your app should hand over control of the user flow to Connect, including back navigation and session termination. Connect's UI always provides users with a way to exit or abort the session, and will communicate the outcome through the callbackUrl with an appropriate status code.
  • Use callback URLs for navigation. Rather than trying to interrupt or monitor the control flow of the Connect Session, provide a callbackUrl that your app can handle. Connect will redirect to this URL with a status parameter indicating the outcome of the session (success, error, or abort). Your app can then check this status and query our system for the resulting data to determine where to navigate the user next. Learn more about linking back to your application from Connect.

For native apps, your callbackUrl should be a deep link (e.g., myapp://connect-callback) that your app is configured to handle. This allows seamless navigation back into your app after the Connect Session completes.

Authenticating Sessions

In order to create an authenticated Connect Session, you need to specify either of these two fields:

  • user: The ID of an existing user
  • userDetails: The details of a user to be created when accessing the connect session. (Verify the email provided does not yet exist in your project, as the request will throw an error otherwise.)

Where to go from here