1Password Connect SDK for JavaScript and TypeScript

You can customize how the library sends requests by providing a custom class that implements the IRequestClient interface. This is useful for handling proxy network access, adding custom logging, or using a specific Node.js HTTP library.

The interface requires a defaultTimeout and a request method.

import { ClientRequestOptions } from "./client";

interface IRequestClient {
    defaultTimeout: number;

    request(
        method: HTTPMethod,
        url: string,
        opts: ClientRequestOptions,
    ): Promise<Response>;
}

To run the provided example, you must have the following components ready:

1. Docker: Installed and running on your machine.
2. 1Password Connect Server: A server deployed on your infrastructure.
3. Connect Token: A token with read/write permissions for at least one vault accessible by the Connect instance.

You can install the @1password/connect SDK using npm or Yarn to allow your JavaScript or TypeScript applications to access 1Password items via a self-hosted 1Password Connect server.

npm install @1password/connect

yarn add @1password/connect

Initialize a new connection to the 1Password Connect server using the OnePasswordConnect function. You must provide the serverURL and an authentication token. You can also enable keepAlive to use HTTP pooling for better performance.

import { OnePasswordConnect } from "@1password/connect";

// Create new connector with HTTP Pooling
const op = OnePasswordConnect({
    serverURL: "http://localhost:8080",
    token: "my-token",
    keepAlive: true,
});

Sections allow you to group related fields within a 1Password item.

• Explicit Creation: Use addSection(sectionName: string) to create an empty section.
• Implicit Creation: When calling addField(opts), providing a sectionName will automatically create that section if it does not already exist.
• Normalization: Section names are normalized using slugify (converted to lowercase and stripped of special characters) to ensure consistent lookups. Section IDs are unique only within the scope of a single item.

To interact with 1Password Connect, use the newConnectClient factory function or instantiate the OPConnect class directly. You must provide a configuration object containing the serverURL of your 1Password Connect instance and a valid token for your Service Account.

Configuration Options (OPConfig)

• serverURL (required): The URL of your 1Password Connect server.
• token (required): The Service Account token.
• httpClient (optional): A custom implementation of IRequestClient if you need to override default HTTP behavior.
• keepAlive (optional): Boolean to enable/disable keep-alive.
• timeout (optional): Request timeout in milliseconds.

import { newConnectClient } from '@1password/connect';

const client = newConnectClient({
    serverURL: 'https://your-connect-server.com',
    token: 'your-service-account-token'
});

The client uses the debug library for runtime information. All logs are under the opconnect namespace. To enable logging, set the DEBUG environment variable to opconnect:*.

DEBUG=opconnect:*

Use the client instance to list all available vaults or retrieve specific vaults by their ID or title.

• listVaults(): Returns a list of all vaults.
• getVault(idOrTitle): Retrieves a vault using either its ID or its title.
• getVaultById(vaultId): Retrieves a vault specifically by its unique ID.
• getVaultByTitle(vaultTitle): Retrieves a vault specifically by its title.

// Get a list of all vaults
const vaults = await op.listVaults();

// Get a specific vault
const vault1 = await op.getVault("vaultId _or_ vaultTitle");
const vault2 = await op.getVaultById("vaultId");
const vault3 = await op.getVaultByTitle("Vault Title");

When instantiating an HTTPClient, you can pass a ClientConfig object to customize the underlying axios instance:

• keepAlive (boolean, optional): If set to true, enables HTTP/HTTPS keep-alive agents to reuse connections.
• timeout (number, optional): The request timeout in milliseconds. Defaults to 15000 (15 seconds).

const config: ClientConfig = {
  keepAlive: true,
  timeout: 5000
};

const client = new HTTPClient(config);