CLI DocumentationSDK DocumentationCommunityHelpCompany
Guides

Create an Access Token

Suggest Edits

There are several ways to create a new Access Token for use with the SDK, including via the CLI Login Commands or via the web app, which is covered in detail in the Authentication section. Below are methods for creating new Access Tokens from within the SDK either using your username and password, or following an SSO web approval flow.

Create a new Access Token using your email and password. Be sure to save the returned Access Token either by calling accessToken.saveToFile() or by saving accessToken.token to a custom storage system.

🚧

Not Supported with SSO

If your team is configured with SSO, you will not have a password for Catalytic and therefore cannot use this method to create Access Tokens. Instead, use the createWithWebApprovalFlow method, or create a new Access Token in the Catalytic Web App and copy or download it to use in your app. See Authentication for details.

Method Signature

create(teamName: string, email: string, password: string): Promise<AccessToken>;
create(teamName: string, email: string, password: string, accessTokenName: string): Promise<AccessToken>;
create(teamName: string, email: string, password: string, callback: (err?: Error, accessToken: AccessToken) => any): void;
create(teamName: string, email: string, password: string, accessTokenName: string, callback: (err?: Error, accessToken: AccessToken) => any): void;

Parameters

ParameterTypeDescription
teamNamestringThe name or hostname of your Catalytic team. This will be
<your-team-name> if you sign into Catalytic at <your-team-name>.pushbot.com
emailstringThe email address you use to log in to Catalytic
passwordstringThe password you use to log in to Catalytic
accessTokenNamestringOptional The name to apply to the new Access Token, which will be visible when managing your Access Tokens via the Catalytic Web App
callback(err?: Error, accessToken: AccessToken) => anyOptional The callback
returnsAccessTokenThe new Access Token

Example

/*
 * This example demonstrates creating a new Access Token using your
 * email and password
 */
const { CatalyticClient } = require('@catalytic/sdk');

const catalytic = new CatalyticClient();

const accessToken = await catalytic.accessTokens.create('your-team', 'your-email', 'your-password', 'your-token-name');

accessToken.saveToFile('default');

The createWithWebApprovalFlow Method

Create a new Access Token and approve it by logging into your Catalytic account. See Authentication for details.

👍

Supported for SSO teams

This method works for all teams, including those with SSO enabled

Method Signature

createWithWebApprovalFlow(teamName: string): Promise<AccessToken>;
createWithWebApprovalFlow(teamName: string, accessTokenName: string): Promise<AccessToken>;
createWithWebApprovalFlow(teamName: string, callback: (err?: Error, accessToken: AccessToken) => any): void;
createWithWebApprovalFlow(teamName: string, accessTokenName: string, callback: (err?: Error, accessToken: AccessToken) => any): void;
ParameterTypeDescription
teamNamestringThe name or hostname of your Catalytic team. This will be
<your-team-name> if you sign into Catalytic at <your-team-name>.pushbot.com
accessTokenNamestringOptional The name to apply to the new Access Token, which will be visible when managing your Access Tokens via the Catalytic Web App
callback(err?: Error, accessToken: AccessToken) => anyOptional The callback
returnsAccessTokenThe new Access Token, initially in the unapproved state.

Example

/*
 * This example demonstrates creating a new Access Token using the
 * web approval flow
 */
const { CatalyticClient } = require('@catalytic/sdk');

const catalytic = new CatalyticClient();

// Create an Access Token that requires approval via the Catalytic UI
const accessToken = await catalytic.accessTokens.createWithWebApprovalFlow('your-team');

// Generate approval url and open in the OS's default browser
const approvalUrl = catalytic.accessTokens.getApprovalUrl(accessToken);
catalytic.accessTokens.openUrl(approvalUrl);

// Wait for token to be approved via Catalytic UI
await catalytic.accessTokens.waitForApproval(accessToken);

// Set AccessToken for use on the constructed `catalytic` client
catalytic.setAccessToken(accessToken);
accessToken.saveToFile('default');

// You are now authenticated and ready to use the Catalytic SDK
// The above only needs to be done once. Now that your Access Token
// is saved as the default Access Token, any new instances of CatalyticClient
// on this machine will use that Access Token

The getApprovalUrl Method

Gets the URL that the user must visit to approve Access Token created with createWithWebApprovalFlow.

Method Signature

getApprovalUrl(accessToken: AccessToken, applicationName?: string): string;
ParameterTypeDescription
accessTokenAccessTokenThe Access Token returned from createWithWebApprovalFlow()
applicationNamestringOptional The name of the application requesting the token. Defaults to "Catalytic SDK"
returnsUriThe URL to direct the user to to approve the new token

Example

See the above getApprovalUrl Example

The openUrl Method

Opens a URL returned from getApprovalUrl in the OS's default browser. Currently supported OS's are OSX, Windows and Linux.

Method Signature

openUrl(url: string): void;

Example

See the above openUrl Example

The waitForApproval Method

Wait for an Access Token created with createWithWebApprovalFlow to be approved by the user in the Catalytic Web App. This method will complete as soon as the user logs in to their Catalytic team and approves the Access Token request. Be sure to save the returned Access Token either by calling accessToken.saveToFile() or by saving accessToken.token to a custom storage system.

Method Signature

waitForApproval(accessToken: AccessToken): Promise<void>;
waitForApproval(accessToken: AccessToken, waitTimeMillis: number): Promise<void>;
waitForApproval(accessToken: AccessToken, callback: ClientMethodCallback<void>): void;
waitForApproval(accessToken: AccessToken, waitTimeMillis: number, callback: ClientMethodCallback<void>): void;
ParameterTypeDescription
accessTokenAccessTokenThe Access Token returned from createWithWebApprovalFlow()
waitTimeMillisnumberOptional number of milliseconds to wait before timing out
callback(err?: Error) => anyOptional The callback
returnsAccessTokenThe approved Access Token

Example

See the above waitForApproval Example

Updated almost 4 years ago