ABasicApplication

Overview #

ABasicApplication is the base class for creating applications that use basic authentication methods like API keys, username/password, or bearer tokens. When you create an application by extending this class, you define how users configure credentials and how those credentials are used in API requests.

Purpose:

  • Define applications with simple authentication (API keys, passwords, tokens)
  • Create configuration forms for users to enter credentials
  • Specify how to make authenticated API requests
  • Check if credentials are properly configured

Location: orchesty-nodejs-sdk/lib/Authorization/Type/Basic/ABasicApplication.ts

When to Use #

Use ABasicApplication when creating an application that authenticates with:

  • API Keys (e.g., X-API-Key: abc123)
  • Username and Password (e.g., HTTP Basic Auth)
  • Bearer Tokens (e.g., Authorization: Bearer xyz789)
  • Custom Tokens (e.g., any static credential)

Don't use for OAuth2 - use AOAuth2Application instead.

Examples of applications:

  • Slack (uses bearer tokens)
  • SendGrid (uses API keys)
  • Many REST APIs with static API keys

Class Hierarchy # 

AApplication
    ↓
ABasicApplication (You extend this)
    ↓
YourCustomApplication (e.g., SlackApplication, SendGridApplication)

Abstract Methods You Must Implement #

getName() # 

public abstract getName(): string

Returns the unique identifier for your application.

Returns: string - Lowercase identifier (no spaces)

Example:

public getName(): string {
    return 'hubspot';
}

getPublicName() # 

public abstract getPublicName(): string

Returns the human-readable display name.

Returns: string - Display name shown to users

Example:

public getPublicName(): string {
    return 'HubSpot CRM';
}

getDescription() # 

public abstract getDescription(): string

Returns a description of what the application does.

Returns: string - Application description

Example:

public getDescription(): string {
    return 'HubSpot is a CRM platform with tools for marketing, sales, and customer service';
}

getFormStack() # 

public abstract getFormStack(): FormStack

Defines the configuration forms users fill out. This is where you specify what credentials and settings users need to provide.

Returns: FormStack - Stack of forms with fields

Example:

import CoreFormsEnum from '../../lib/Application/Base/CoreFormsEnum';
import Field from '../../lib/Application/Model/Form/Field';
import FieldType from '../../lib/Application/Model/Form/FieldType';
import Form from '../../lib/Application/Model/Form/Form';
import FormStack from '../../lib/Application/Model/Form/FormStack';

public getFormStack(): FormStack {
    const apiKeyField = new Field(
        FieldType.TEXT,
        'api_key',
        'API Key'
    );
    
    const form = new Form(
        CoreFormsEnum.AUTHORIZATION_FORM,
        'Authorization'
    );
    form.addField(apiKeyField);
    
    const formStack = new FormStack();
    formStack.addForm(form);
    
    return formStack;
}

getRequestDto() # 

public abstract getRequestDto(
    dto: AProcessDto,
    applicationInstall: ApplicationInstall,
    method: HttpMethods,
    url?: string,
    data?: unknown
): RequestDto | Promise<RequestDto>

Creates an authenticated HTTP request. This is where you specify how to add credentials to API calls.

Parameters:

ParameterTypeDescription
dtoAProcessDtoProcess context
applicationInstallApplicationInstallUser's credentials
methodHttpMethodsHTTP method (GET, POST, etc.)
urlstring | undefinedAPI endpoint URL
dataunknown | undefinedRequest body

Returns: RequestDto | Promise<RequestDto> - Configured request

Example:

public getRequestDto(
    dto: AProcessDto,
    applicationInstall: ApplicationInstall,
    method: HttpMethods,
    url?: string,
    data?: unknown
): RequestDto {
    const settings = applicationInstall.getSettings();
    const apiKey = settings[CoreFormsEnum.AUTHORIZATION_FORM]['api_key'];
    
    const requestDto = new RequestDto(url ?? '', method, dto, data);
    requestDto.setHeaders({
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    });
    
    return requestDto;
}

Inherited Methods Available #

getAuthorizationType() # 

public getAuthorizationType(): AuthorizationTypeEnum

Returns AuthorizationTypeEnum.BASIC (automatically provided by ABasicApplication).

Returns: AuthorizationTypeEnum.BASIC

isAuthorized() # 

public isAuthorized(applicationInstall: ApplicationInstall): boolean

Checks if the application has valid credentials configured. Automatically checks for user + password or token in the authorization form.

Parameters:

ParameterTypeDescription
applicationInstallApplicationInstallInstallation to check

Returns: boolean - True if credentials are configured

Logic: Returns true if settings contain:

  • user AND password, OR
  • token

Usage Examples #

Simple API Key Application #

From: orchesty-nodejs-sdk/test/Application/TestBasicApplication.ts (adapted)

import CoreFormsEnum from '../../lib/Application/Base/CoreFormsEnum';
import { ApplicationInstall } from '../../lib/Application/Database/ApplicationInstall';
import Field from '../../lib/Application/Model/Form/Field';
import FieldType from '../../lib/Application/Model/Form/FieldType';
import Form from '../../lib/Application/Model/Form/Form';
import FormStack from '../../lib/Application/Model/Form/FormStack';
import { ABasicApplication } from '../../lib/Authorization/Type/Basic/ABasicApplication';
import RequestDto from '../../lib/Transport/Curl/RequestDto';
import { HttpMethods } from '../../lib/Transport/HttpMethods';
import ProcessDto from '../../lib/Utils/ProcessDto';

export default class SendGridApplication extends ABasicApplication {

    public getName(): string {
        return 'sendgrid';
    }

    public getPublicName(): string {
        return 'SendGrid';
    }

    public getDescription(): string {
        return 'Email delivery service';
    }

    public getFormStack(): FormStack {
        // Create API key field
        const apiKeyField = new Field(
            FieldType.PASSWORD,  // Use PASSWORD type to hide the key
            'api_key',
            'API Key'
        );
        apiKeyField.setDescription('Your SendGrid API key');
        apiKeyField.setRequired(true);
        
        // Create authorization form
        const form = new Form(
            CoreFormsEnum.AUTHORIZATION_FORM,
            'Authorization'
        );
        form.addField(apiKeyField);
        
        // Return form stack
        const formStack = new FormStack();
        formStack.addForm(form);
        
        return formStack;
    }

    public getRequestDto(
        dto: ProcessDto,
        applicationInstall: ApplicationInstall,
        method: HttpMethods,
        url?: string,
        data?: unknown
    ): RequestDto {
        // Get API key from settings
        const settings = applicationInstall.getSettings();
        const apiKey = settings[CoreFormsEnum.AUTHORIZATION_FORM]['api_key'];
        
        // Create request with API key in header
        const requestDto = new RequestDto(url ?? '', method, dto, data);
        requestDto.setHeaders({
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        });
        
        return requestDto;
    }
}

Username/Password Application #

From: orchesty-nodejs-sdk/test/Application/TestBasicApplication.ts

import { PASSWORD, USER } from '../../lib/Authorization/Type/Basic/ABasicApplication';

export default class DatabaseApplication extends ABasicApplication {

    public getName(): string {
        return 'mysql';
    }

    public getPublicName(): string {
        return 'MySQL Database';
    }

    public getDescription(): string {
        return 'MySQL database connection';
    }

    public getFormStack(): FormStack {
        // Create username field
        const userField = new Field(FieldType.TEXT, USER, 'Username');
        userField.setRequired(true);
        
        // Create password field
        const passwordField = new Field(FieldType.PASSWORD, PASSWORD, 'Password');
        passwordField.setRequired(true);
        
        // Add host field for additional configuration
        const hostField = new Field(FieldType.TEXT, 'host', 'Database Host');
        hostField.setValue('localhost');
        
        // Create forms
        const authForm = new Form(
            CoreFormsEnum.AUTHORIZATION_FORM,
            'Authorization'
        );
        authForm.addField(userField);
        authForm.addField(passwordField);
        
        const configForm = new Form('configForm', 'Configuration');
        configForm.addField(hostField);
        
        const formStack = new FormStack();
        formStack.addForm(authForm);
        formStack.addForm(configForm);
        
        return formStack;
    }

    public getRequestDto(
        dto: ProcessDto,
        applicationInstall: ApplicationInstall,
        method: HttpMethods,
        url?: string,
        data?: unknown
    ): RequestDto {
        const settings = applicationInstall.getSettings();
        const authForm = settings[CoreFormsEnum.AUTHORIZATION_FORM];
        const username = authForm[USER];
        const password = authForm[PASSWORD];
        
        // Create request with HTTP Basic Auth
        const requestDto = new RequestDto(url ?? '', method, dto, data);
        requestDto.setAuth(username, password);
        
        return requestDto;
    }
}

Bearer Token Application # 

export default class SlackApplication extends ABasicApplication {

    public getName(): string {
        return 'slack';
    }

    public getPublicName(): string {
        return 'Slack';
    }

    public getDescription(): string {
        return 'Team communication platform';
    }

    public getFormStack(): FormStack {
        const tokenField = new Field(
            FieldType.PASSWORD,
            'token',
            'Bot Token'
        );
        tokenField.setDescription('Your Slack Bot User OAuth Token (starts with xoxb-)');
        tokenField.setRequired(true);
        
        const form = new Form(
            CoreFormsEnum.AUTHORIZATION_FORM,
            'Authorization'
        );
        form.addField(tokenField);
        
        const formStack = new FormStack();
        formStack.addForm(form);
        
        return formStack;
    }

    public getRequestDto(
        dto: ProcessDto,
        applicationInstall: ApplicationInstall,
        method: HttpMethods,
        url?: string,
        data?: unknown
    ): RequestDto {
        const settings = applicationInstall.getSettings();
        const token = settings[CoreFormsEnum.AUTHORIZATION_FORM]['token'];
        
        const requestDto = new RequestDto(url ?? '', method, dto, data);
        requestDto.setHeaders({
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json'
        });
        
        return requestDto;
    }
}

Complete Application Example #

From: orchesty-nodejs-sdk/test/Application/TestBasicApplication.ts

export default class TestBasicApplication extends ABasicApplication {

    // Custom synchronous methods (optional)
    public syncTestSyncMethod(): string {
        return JSON.stringify({
            param1: 'p1',
            param2: 'p2'
        });
    }

    public getDescription(): string {
        return 'Test description';
    }

    public getName(): string {
        return 'test';
    }

    public getPublicName(): string {
        return 'Test application';
    }

    public getFormStack(): FormStack {
        const label = 'testLabel';

        // Authorization form
        const userField = new Field(FieldType.TEXT, USER, label);
        const passwordField = new Field(FieldType.PASSWORD, PASSWORD, label);

        const authForm = new Form(CoreFormsEnum.AUTHORIZATION_FORM, 'testPublicName');
        authForm.addField(passwordField);
        authForm.addField(userField);

        // Custom configuration form
        const hostField = new Field(FieldType.TEXT, 'host', label);
        const multiSelect = new Field(FieldType.MULTI_SELECT, 'multi', label);
        const databaseField = new Field(FieldType.TEXT, 'database', label);

        const configForm = new Form('testForm', 'testPublicName');
        configForm
            .addField(databaseField)
            .addField(multiSelect)
            .addField(hostField);

        const formStack = new FormStack();
        formStack.addForm(authForm);
        formStack.addForm(configForm);
        
        return formStack;
    }

    public getRequestDto(
        dto: ProcessDto,
        applicationInstall: ApplicationInstall,
        method: HttpMethods,
        url?: string,
        data?: unknown
    ): RequestDto {
        return new RequestDto(url ?? '', method, dto, data);
    }
}

Common Patterns #

Pattern 1: Multiple Authentication Options # 

public getFormStack(): FormStack {
    // Allow user to choose between API key or username/password
    const apiKeyField = new Field(FieldType.PASSWORD, 'api_key', 'API Key');
    const userField = new Field(FieldType.TEXT, USER, 'Username');
    const passwordField = new Field(FieldType.PASSWORD, PASSWORD, 'Password');
    
    const form = new Form(CoreFormsEnum.AUTHORIZATION_FORM, 'Authorization');
    form.addField(apiKeyField);
    form.addField(userField);
    form.addField(passwordField);
    
    const formStack = new FormStack();
    formStack.addForm(form);
    
    return formStack;
}

public getRequestDto(
    dto: ProcessDto,
    applicationInstall: ApplicationInstall,
    method: HttpMethods,
    url?: string,
    data?: unknown
): RequestDto {
    const settings = applicationInstall.getSettings();
    const authForm = settings[CoreFormsEnum.AUTHORIZATION_FORM];
    
    const requestDto = new RequestDto(url ?? '', method, dto, data);
    
    // Use API key if provided, otherwise username/password
    if (authForm['api_key']) {
        requestDto.setHeaders({ 'X-API-Key': authForm['api_key'] });
    } else if (authForm[USER] && authForm[PASSWORD]) {
        requestDto.setAuth(authForm[USER], authForm[PASSWORD]);
    }
    
    return requestDto;
}

Pattern 2: Base URL Configuration # 

public getFormStack(): FormStack {
    const apiKeyField = new Field(FieldType.PASSWORD, 'api_key', 'API Key');
    const authForm = new Form(CoreFormsEnum.AUTHORIZATION_FORM, 'Authorization');
    authForm.addField(apiKeyField);
    
    // Add base URL configuration
    const baseUrlField = new Field(FieldType.URL, 'base_url', 'API Base URL');
    baseUrlField.setValue('https://api.example.com');
    baseUrlField.setDescription('Your instance URL');
    
    const configForm = new Form('configForm', 'Configuration');
    configForm.addField(baseUrlField);
    
    const formStack = new FormStack();
    formStack.addForm(authForm);
    formStack.addForm(configForm);
    
    return formStack;
}

public getRequestDto(
    dto: ProcessDto,
    applicationInstall: ApplicationInstall,
    method: HttpMethods,
    url?: string,
    data?: unknown
): RequestDto {
    const settings = applicationInstall.getSettings();
    const baseUrl = settings['configForm']['base_url'];
    const apiKey = settings[CoreFormsEnum.AUTHORIZATION_FORM]['api_key'];
    
    // Combine base URL with endpoint
    const fullUrl = `${baseUrl}${url}`;
    
    const requestDto = new RequestDto(fullUrl, method, dto, data);
    requestDto.setHeaders({ 'Authorization': `Bearer ${apiKey}` });
    
    return requestDto;
}

Pattern 3: Custom Headers # 

public getRequestDto(
    dto: ProcessDto,
    applicationInstall: ApplicationInstall,
    method: HttpMethods,
    url?: string,
    data?: unknown
): RequestDto {
    const settings = applicationInstall.getSettings();
    const apiKey = settings[CoreFormsEnum.AUTHORIZATION_FORM]['api_key'];
    
    const requestDto = new RequestDto(url ?? '', method, dto, data);
    requestDto.setHeaders({
        'X-API-Key': apiKey,
        'X-Client-ID': 'orchesty-sdk',
        'X-API-Version': '2023-01',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    });
    
    return requestDto;
}

See Also #

© 2025 Orchesty Solutions. All rights reserved.