If you're in an environment which can keep secrets and is used for many of your users (e.g. a Web or Application Server), you should use the Platform API to retrieve user access tokens to 3rd Party Applications.
The Get User Connection Endpoint can be used with a Platform API Key to retrieve a single user's connection to a 3rd party application.
All you need to know is the user's unique ID as provided to Xkit when provisioning and the slug
of the connector which you configured in the Xkit Dashboard, usually a short string like slack
.
A Node.js example is below:
import axios from 'axios'
const PUBLISHABLE_KEY = process.env.XKIT_PUBLISHABLE_KEY
const SECRET_KEY = process.env.XKIT_SECRET_KEY
async function getAccessToken(userId, connectorSlug) {
const {
connection,
connector,
authorization
} = await axios({
baseUrl: 'https://app.xkit.co/api/platform',
url: `/connections/${userId}/${connectorSlug}`,
auth: {
username: PUBLISHABLE_KEY,
password: SECRET_KEY
}
})
if (!connection.enabled) {
console.log(`User ${userId} has not enabled ${connectorSlug}`)
} else if (authorization.status !== "active") {
console.log(`User ${userId} has authorization for ${connectorSlug} in a ${authorization.status} status`)
} else {
return authorization.access_token
}
}
// ...
const slackToken = await getAccessToken('some-user-id', 'slack')
Group Tokens
Retrieving access tokens for a Group of users is very similar, but rather than using the Get User Connection endpoint, you'll use the Get Group Connection endpoint.
It takes all of the same parameters, except that it uses the ID of the group in place of the ID of the user.
The return values from this endpoint are identical, as it finds the best available connection to return to you.
Access Tokens Unavailable
If the user has not yet enabled the connection, the enabled
parameter of the connection
will be false
.
If the user has enabled the connection, but no access token is available, the access_token
parameter of the authorization
will be empty, and the status
parameter will be something other than active
(most commonly error
).
In any case where the API does not return an access token but you are expecting one, you should redirect the user to your Xkit catalog to either set up or repair the connection.
Unless you are self-hosting , the catalog is available at https://<your-slug>.xkit.co
, and you can use the returned slug
parameter in the connector
to send the user directly to the affected page: https://<your-slug>.xkit.co/connectors/<connector_slug>
.
Refreshing Access Tokens
This endpoint will automatically refresh expired access tokens if the corresponding service supports it. If you receive an error message from the service that an access token is expired or invalid, call this endpoint again to receive a new access token or the updated status of the connection.
Updated 3 months ago