The xkit Developer Hub

Welcome to the xkit developer hub. You'll find comprehensive guides and documentation to help you start working with xkit as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Amazon Cognito

Authenticating users with Amazon Cognito

If you use Amazon Cognito to authenticate your users, you can use the same authentication to log users into Xkit to connect other apps to yours.


token_use and scopes not validated

Xkit does not validate the token_use or scopes claim, so both ID and Access tokens with any (or no) granted scopes will be able to log into Xkit.

To set up Amazon Cognito with Xkit, use the following steps:

  1. Click on Settings in the left sidebar and scroll down to "User Tokens"
  2. Click "Add Custom Issuer"
  3. For the "iss Claim", use the value https://cognito-idp.<region>.amazonaws.com/<userpoolID> where <region> is the region in which you created the User Pool and <userpoolID> is the identifier for your User Pool.
  4. If you are using ID Tokens, for the "aud Claim", use app client ID created in the Amazon Cognito user pool. If you are using Access Tokens, leave the "aud Claim" field blank.
  5. For the "User ID Claim", keep it as sub.
  6. Optionally for the "Friendly User Name Claim", use the value email
  7. For the "JSON Web Key Set URL", use the value https://cognito-idp.<region>.amazonaws.com/<userPoolId>/.well-known/jwks.json where <region> is the region in which you created the User Pool and <userpoolID> is the identifier for your User Pool.
  8. Click "Save"

Your Xkit installation will now be able to use your Amazon Cognito tokens to login to Xkit.

An example usage is below:

import {
} from 'amazon-cognito-identity-js'

const userPool = new CognitoUserPool({
  UserPoolId: <userpoolID>,
  ClientId: <clientID>
const cognitoUser = new CognitoUser({
  Username: <username>,
  Pool: userPool
const authenticationDetails = new AuthenticationDetails({
  Usernamae: <username>,
  Password: <password>

cognitoUser.authenticateUser(authenticationDetails, {
  onSuccess: async function (result) {
    const accessToken = result.getAccessToken().getJwtToken()
    await window.xkit.login(accessToken)

User Groups

If you want to use the User Groups feature with Cognito, you have a few options.

If your users are only ever members of one group, you can supply the cognito:groups claim as your "Group ID Claim". However, note that any member of multiple groups will have unexpected behavior.

You may also be able to use the cognito:preferred_role claim as your "Group ID Claim", but again use that with caution.

You can add custom claims which you can also set as your "Group ID Claim", giving you complete control over which Xkit group your users belong to.

Further Reading

For more details about this process, check out the Custom Token Issuer Guide on Xkit and the Verifying a JSON Web Token documentation on Amazon Cognito.

Updated 5 months ago

Amazon Cognito

Authenticating users with Amazon Cognito

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.