Authentication

To access integration engine through the Rest API or Front-end SDK, you need an access token that incapsulates information about:

Workspace you want to interact with.
Permissions you want to have.
Your customer that is using the integration.

Here is how to get the token.

Access Token

Never generate authentication token on your front-end.
It contains Workspace Secret that should never be exposed to your users. Only generate it on the backend.

Workspace Key/Secret Token Signing

To authenticate, create a JSON Web Token with your user's data:

import jwt from 'jsonwebtoken'
// Your workspace key and secret.
// You can find them on the Settings page.
const WORKSPACE_KEY = '<WORKSPACE_KEY>'
const WORKSPACE_SECRET = '<WORKSPACE_SECRET>'

const tokenData = {
  // Identifier of your customer (user, team, or organization).
  id: '{CUSTOMER_ID}',
  // Human-readable customer name.
  name: '{CUSTOMER_NAME}',
  // (optional) Any user fields you want to attach to your customer.
  fields: {
    userField: '<user field value>'
  }
}

const options = {
  issuer: WORKSPACE_KEY,
  // To prevent token from being used for too long
  expiresIn: 7200,
  // HS256 signing algorithm is used by default,
  // but we recommend to go with more secure option like HS512.
  algorithm: 'HS512'
}

const token = jwt.sign(tokenData, WORKSPACE_SECRET, options)

import datetime
import jwt

# Your workspace key and secret.
# You can find them on the Settings page.
WORKSPACE_KEY = "f88f52bc-57a9-47e3-93b3-843fa0dd5708"
WORKSPACE_SECRET = "2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66"

encoded_jwt = jwt.encode(
    {
      # ID of your customer in your system.
      # It will be used to identify customer in Integration.app
      "id": "{CUSTOMER_ID}",
      # Human-readable name (it will simplify troubleshooting)
      "name": "{CUSTOMER_NAME}",
      "iss": WORKSPACE_KEY,
      # Any customer fields you want to attach to your user.
      "fields": {
        "field1": "<field value>"
      }
      "exp": datetime.datetime.now() + datetime.timedelta(seconds=1440)
    }, WORKSPACE_SECRET, algorithm="HS256")

import (
    "time"
    "github.com/dgrijalva/jwt-go"
)

var WORKSPACE_KEY = "f88f52bc-57a9-47e3-93b3-843fa0dd5708"
var WORKSPACE_SECRET = "2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66"

var SigningKey = []byte(WORKSPACE_SECRET)


claims := jwt.MapClaims{
    // Identifier of your customer (user, team, or organization).
    "id" : "{CUSTOMER_ID}",
    // Human-readable customer name.
    "name": "{CUSTOMER_NAME}",
    // To prevent token from being used for too long
    "exp": time.Now().Add(time.Hour * 24).Unix(),
    "iss": WORKSPACE_KEY,
    }

token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
tokenString, err := token.SignedString(SigningKey)

require 'jwt'

WORKSPACE_SECRET = '2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66'
WORKSPACE_KEY = 'f88f52bc-57a9-47e3-93b3-843fa0dd5708'

payload = {
  id: '{CUSTOMER_ID}',
  name: '{CUSTOMER_NAME}',
  iss: WORKSPACE_KEY,
  exp: Time.now.to_i + 60 * 60 * 6, # Expiration time (6 hours from now)
}

token = JWT.encode(payload, WORKSPACE_SECRET, 'HS256')

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

import javax.crypto.spec.SecretKeySpec;
import java.time.temporal.ChronoUnit;
import java.util.Date;


String workspaceKey = "f88f52bc-57a9-47e3-93b3-843fa0dd5708";
String workspaceSecret = "2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66";

String jwtToken = Jwts.builder()
        .claim("id", "{CUSTOMER_ID}") // Identifier of user or organization.
        .claim("name", "{CUSTOMER_NAME}") // Human-readable name (it will simplify troubleshooting)
        // .claim("fields", <user fields value>) (optional) Any user fields you want to attach to your user.
        .setExpiration(Date.from(new Date().toInstant().plus(14400, ChronoUnit.SECONDS))) // To prevent token from being used for too long
        .setIssuer(workspaceKey)
        .signWith(new SecretKeySpec(workspaceSecret.getBytes(), SignatureAlgorithm.HS256.getJcaName()), SignatureAlgorithm.HS256)
        .setHeaderParam("typ", "JWT")
        .compact();

use FirebaseJWTJWT;

// Your workspace key and secret.
// You can find them on the Settings page.
$secret = '2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66';
$key = 'f88f52bc-57a9-47e3-93b3-843fa0dd5708';

$payload = [
    'id' => "{CUSTOMER_ID}",  // ID of your customer in your system. It will be used to identify customer in Integration.app
    'name' => "{CUSTOMER_NAME}", // Human-readable customer name (it will simplify troubleshooting)
    'iss' => $key,
    'exp' => time() + 60 * 60 * 24 * 60, // To prevent token from being used for too long
];
$token = JWT::encode($payload, $secret, 'HS256');

Default algorithm for signing tokens is HS256, but we recommend to go with more secure option like ES256 or RS256.
We support all the algorithms supported by jsonwebtoken library.

You can find your Workspace Key and Secret on the Settings page.

Then use this token to initialize Javascript SDK or in the REST API requests.

Authentication token contains information integration.app needs to know about your user:

id - user ID, unique within the workspace.
name - username to identify them user in the integration.app UI.
fields - any additional information you want to store about the user. For example:
- API key for integration.app to call your API on behalf of this user.
- User preferences for integrations.

The token is signed by the Secret Key you can find in your Workspace Settings.

Public/Private Key Token Signing

Alternatively, you can use public/private key pair to sign the token. To do that, you need to pass the private key to the sign method instead of the secret and provide the public key in the Workspace Settings. This is more secure option, and we recommend to use it.

import jwt from 'jsonwebtoken'

// Your workspace key and secret.
// You can find them on the Settings page.
const WORKSPACE_KEY = '<WORKSPACE_KEY>'

// Do not expose your private key to anyone. You should only use it to sign tokens.
const PRIVATE_KEY = `<YOUR PRIVATE KEY>`

const tokenData = {
  // Identifier of user or organization.
  id: '{USER_ID}',
  // Human-readable name (it will simplify troubleshooting)
  name: '{USER_NAME}',
  // (optional) Any user fields you want to attach to your user.
  fields: {
    userField: '<user field value>'
  }
}

const options = {
  issuer: WORKSPACE_KEY,
  // To prevent token from being used for too long
  expiresIn: 7200,

  algorithm: 'ES256' // or any other asymmetric algorithm you prefer (RS*, ES*, PS*)
}

const token = jwt.sign(tokenData, PRIVATE_KEY, options)

Using Organization Tokens

If you want to set up integrations not for a single user, but for a larger entity like organization,
you should use the organization ID instead of an individual user ID.

To check that you generated the token correctly, paste it here:

import { IntegrationAppClient } from '@integration-app/sdk'

const integrationApp = new IntegrationAppClient({
  token: '{TOKEN}',
})

const self = await integrationApp.self.get()

You can also use the JWT token explorer at jwt.io.

Admin Token

When you want to make admin-level actions like editing users, you need to generate an Admin Token. It is generated in exactly the same way, except:

You MUST add isAdmin claim to it with any non-empty value.
You SHOULD NOT add id claim to it - admin token should not be attached to any user.

Here is an example of generating an admin token:

import jwt from 'jsonwebtoken'
// Your workspace key and secret.
// You can find them on the Settings page.
const WORKSPACE_KEY = '<WORKSPACE_KEY>'
const WORKSPACE_SECRET = '<WORKSPACE_SECRET>'

const tokenData = {
  isAdmin: true
}

const options = {
  issuer: WORKSPACE_KEY,
  // To prevent token from being used for too long
  expiresIn: 7200,
  // HS256 signing algorithm is used by default,
  // but we recommend to go with more secure option like HS512.
  algorithm: 'HS512'
}

const token = jwt.sign(tokenData, WORKSPACE_SECRET, options)

Customers

People or groups using integrations in your app.

Javascript SDK

Use integration.app in your app's front-end.

Access Token

Workspace Key/Secret Token Signing

Public/Private Key Token Signing

Using Organization Tokens

Admin Token

Read More