Migrating to Contexts

If you're using Xkit user tokens and/or Xkit Groups, you'll need to migrate your usage to Xkit Contexts in order to take full advantage of new features and to better model your application's permissions structure.

Contexts are generic entities that you can use to model your application within Xkit. Depending on your app and the integrations you're building, Contexts can be individual users, companies, projects, teams, or any other entity that's meaningful.

Full documentation for what Contexts are and how they work is here: Authenticating Users as Contexts.

This document will focus specifically on migrating from an existing Xkit setup to one that uses Contexts.

There are three steps to the migration:

1. Change the endpoint used to access credentials
2. Generate context tokens for your users
3. Login your users with context tokens

1. Change the endpoint used to access credentials

All of your users and groups already exist within Xkit as Contexts (you can verify this on the Connections Dashboard).

To access the credentials associated with the Context (rather than the User or Group), you use the new Get Connection by Connector endpoint.

The URL for that endpoint is:
https://app.xkit.co/api/platform/contexts/:external_id/connections/:connector_slug

If you're currently using Groups, you should change the groups segment in your current URL to contexts:
https://app.xkit.co/api/platform/groups/:external_group_id/connections/:connector_slug -> https://app.xkit.co/api/platform/contexts/:external_group_id/connections/:connector_slug

If you're accessing credentials for individual users, you should change the users segment in your current URL to contexts:
https://app.xkit.co/api/platform/users/:external_user_id/connections/:connector_slug -> https://app.xkit.co/api/platform/contexts/:external_user_id/connections/:connector_slug

The return value for this endpoint is the same as the current endpoint.

📘

Can be done separately

This step must be completed before steps 2 and 3, but can be done before steps 2 and 3 with no impact to your current usage of Xkit.

2. Generate context tokens for your users

To log your user in as an Xkit Context, they need an Xkit Context Token.

To generate a token, you call the Create Context endpoint with the External ID of the context.

If you're currently using Groups, this External ID should be the Group's External ID (e.g. Company ID, Team ID). If you're currently doing individual integrations, this External ID should be the user's ID.

With Contexts, there is no differentiation between two different users who have access to the same context - it is up to your application to determine which users get access to which contexts (via generated Context Tokens).

Since all your existing users and groups are already replicated to contexts, as long as you're using the same External ID, your users will have full access to any previously connected integrations.

Here's an example for how to generate a Context Token:

const sampleUser = {
  id: "my_sample_user_id",
  email: "[email protected]",
  apiKey: "secret_user_api_key",
  company: {
    id: "my_sample_company_id",
    name: "Acme, Inc.",
    apiKey: "secret_acme_api_key"
  }
}

const { access_token } = await axios({
  method: 'post',
  url: 'https://app.xkit.co/api/platform/context',
  auth: {
    username: XKIT_PUBLISHABLE_KEY,
    password: XKIT_SECRET_KEY
  },
  data: {
    // Using the current user's company as the context
    context: {
      external_id: sampleUser.company.id,
      // Optional friendly name
      external_name: sampleUser.company.name,
      // Optional extra attributes
      apiKey: sampleUser.company.apiKey
    }
  }
})

const sampleUser = {
  id: "my_sample_user_id",
  email: "[email protected]",
  apiKey: "secret_user_api_key",
  company: {
    id: "my_sample_company_id",
    name: "Acme, Inc.",
    apiKey: "secret_acme_api_key"
  }
}

const { access_token } = await axios({
  method: 'post',
  url: 'https://app.xkit.co/api/platform/context',
  auth: {
    username: XKIT_PUBLISHABLE_KEY,
    password: XKIT_SECRET_KEY
  },
  data: {
    // Using the current user as the context
    context: {
      external_id: sampleUser.id,
      // Optional friendly name
      external_name: sampleUser.email,
      // Optional extra attributes
      apiKey: sampleUser.apiKey
    }
  }
})

It is recommended that you generate context tokens via a dedicated API endpoint that can be called from the front-end of your app.

3. Login your users with context tokens

Now that you have a context token generated, you can log your user into Xkit as the given context.

You do this with the same xkit.login function you're used to.

If you generate context tokens via a dedicated API endpoint (as is recommended), you should use a Token Callback function to retrieve the tokens in xkit.login. When you use a Token Callback function, xkit.js will call the function when the current token expires. This will prevent users from getting logged out of Xkit (and potentially redirected) during a valid session.

Presuming that your dedicated API endpoint is POST /xkit-token and it returns an object with a token property containing the generated Xkit Context Token, using a Token Callback function would look something like the below:

import axios from 'axios'
import createXkit from '@xkit-co/xkit.js`

const xkit = createXkit('<your-slug>.xkit.co')

xkit.login(async () => {
  const { token } = await axios({
    method: 'post',
    url: '/xkit-token'
  })

  return token
})