NodeJS Library for the Xenqu API
NodeJS Implementation of the Xenqu API (with types) Based off of these API Docs
Getting Started: Install:
npm install @essium-llc/lib-xenqu-nodejs Usage
There are 4 ways to initialize your API instance:
- Create an API Instance using a Private Key:
import XenquAPI from "lib-xenqu-nodejs";
const API = new XenquAPI("client_id", "client_secret", "private_key", "subscriber", 'https://xenqu.com/api');
await API.init(); // Connects to API using OAuth 2.0 to get OAuth 1.0 credentials OR
- Create an API Instance using a Username/Password Authentication, along with embedding the Xenqu login portal
import XenquAPI, {XenquAPIBoot} from "lib-xenqu-nodejs";
const boot = await XenquAPIBoot('https://xenqu.com/api', 'your-app-id', 'your-site-profile')
const API = new XenquAPI(boot._m, boot._s, null, null, 'https://stage.xenqu.com/api', true);
const tempToken = await API.startWebAuth('your-callback-url');
// Use the tempToken to embed `https://xenqu.com/login.html?oauth_token=${tempToken}`
// login.html will load username and password field. Once UN/PW are accepted
// Xenqu will automatically call your callback url with encoded form data.
// You will need to decode the returned string and pass the oauth_verifier
// data to the following function
const tokensToSave = await API.finishWebAuth(oauth_verifier); // Save these tokens (securely) if you'd like to attempt reauthoriztion later! OR
- Create an API Instance using a Username/Password Authentication
import XenquAPI, {XenquAPIBoot} from "@essium-llc/lib-xenqu-nodejs";
const boot = await XenquAPIBoot('https://xenqu.com/api', 'your-app-id', 'your-site-profile')
const API = new XenquAPI(boot._m, boot._s, null, null, 'https://stage.xenqu.com/api', true);
// Typically, the client ID and client secret are different for the middle requests in
// our oauth process. These will be provided if this is the case. Otherwise,
// you may proceed by setting these to the same as above
const loginClient = 'your-login-client-id'; // boot._m
const loginSecret = 'your-login-client-secret'; // boot._s
// A registered callback must be used here. Although the responses from the callbacks aren't
// ever used, the oauth requests still require a registered callback url to be sent
const callback = 'your-registered-callback';
// Authenticator is the method of authentication that you want to use.
// 'default' is for Username/Password authentication
// 'openid' is used for SSO applications
const authenticator = 'default'; // 'openid'
// Additional parameters includes the parameters that are used in the authentication request.
// If your authenticator is 'default' you'll need to include 'user_name' and 'user_pass'
// If your authenticator is 'openid' you'll need to include 'provider' and any other fields
// that that SSO provider requires to be sent.
const extraParams = { user_name: 'username', user_pass: 'password' };
// These are example parameters for Microsoft SSO
const extraParams = { provider: 'microsoft', id_token: 'microsoft-id-token' }
// Attempt the full xenqu oauth authentication flow in one fell swoop
const tokensToSave = await API.attemptAuthWithUNandPWorSSO(loginClient, loginSecret, callback, authenticator, extraParams); // Save these tokens (securely) if you'd like to attempt reauthoriztion later! If you are having issues trying to use the whole auth flow at once, you can debug each part by breaking apart the requests:
import XenquAPI, {XenquAPIBoot} from "@essium-llc/lib-xenqu-nodejs";
const boot = await XenquAPIBoot('https://xenqu.com/api', 'your-app-id', 'your-site-profile')
const API = new XenquAPI(boot._m, boot._s, null, null, 'https://stage.xenqu.com/api', true);
// See above example for explination of these variables and what they all mean
const loginClient = 'your-login-client-id'; // boot._m
const loginSecret = 'your-login-client-secret'; // boot._s
const callback = 'your-registered-callback';
const authenticator = 'default'; // 'openid'
const extraParams = { user_name: 'username', user_pass: 'password' };
await API.startWebAuth('your-callback-url');
await API.authenticate(loginClient , loginSecret , callback, authenticator, extraParams);
const verifierWhole = await API.authorize(loginClient, loginSecret, callback);
const verifierSplit = verifierWhole.split('&')[1].split('=')[1]; // Split form-data response to get verifier
const tokensToSave = await API.finishWebAuth(verifierSplit); // Save these tokens (securely) if you'd like to attempt reauthoriztion later! OR
- Create an API Instance using old OAuth1.0 credentials.
- This is useful if you have a user logged in on the web, and they close and re-open their browsing window. If you cached the credentials, you can reload the user without having them re-enter their login information again.
- This isn't as useful in a private-key authenticated API instance, as you can always renew your keys by calling
API.init()
import XenquAPI from "lib-xenqu-nodejs";
const oldCreds = new new OAuth1Credentials({
consumer_key: 'your-consumer-key',
consumer_secret: 'your-consumer-secret',
token: 'your-token',
token_secret: 'your-secret',
})
const API = new XenquAPI(oldCreds.consumerKey, oldCreds.consumerSecret, "private_key", "subscriber", 'https://xenqu.com/api');
// OR, If you're using Web-Style authentication
const API = new XenquAPI(oldCreds.consumerKey, oldCreds.consumerSecret, null, null, 'https://xenqu.com/api', true);
// Set the second parameter to true to attempt to renew the keys
const renewedCreds = await API.tryOldCredentials(oldCreds, false); Once initialized, you can call any API route available on these API Docs. If you find a missing route, please create an issue.
Access API Routes:
API.account // Account Routes
API.contact // Contact Routes
API.tracking // Tracking Routes
API.forms // Form Routes
API.reports // Report Routes
API.files // File Routes
API.search // Search Routes Other Implementations
Ruby
.NET
Our .NET implementation can access reports. We've used this in RPA projects using Automation Anywhere. It should also be possible to get it to work with UiPath, or can used stand-alone to build utility apps.