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.

Authenticated vs. Unauthenticated 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.)

It is also possible to create unauthenticated Connect Sessions by omitting the user and userDetails fields in the creation request. Redirecting the user to an unauthenticated Session will require them to go through our login flow with an OTP.

Where to go from here