Infisical Node.js SDK

If you’re working with Node.js, the official Infisical Node SDK package is the easiest way to fetch and work with secrets for your application.

Basic Usage

import express from "express";

import { InfisicalClient } from "@infisical/sdk";

const app = express();

const PORT = 3000;

const client = new InfisicalClient({
    siteUrl: "https://app.infisical.com", // Optional, defaults to https://app.infisical.com
    auth: {
      universalAuth: {
        clientId: "YOUR_CLIENT_ID",
        clientSecret: "YOUR_CLIENT_SECRET"
      }
    }
});

app.get("/", async (req, res) => {
  // Access the secret
  
    const name = await client.getSecret({
        environment: "dev",
        projectId: "PROJECT_ID",
        path: "/",
        type: "shared",
        secretName: "NAME"
    });

    res.send(`Hello! My name is: ${name.secretValue}`);
});

app.listen(PORT, async () => {
    // initialize client

    console.log(`App listening on port ${PORT}`);
});

This example demonstrates how to use the Infisical Node SDK with an Express application. The application retrieves a secret named “NAME” and responds to requests with a greeting that includes the secret value.

We do not recommend hardcoding your Machine Identity Tokens. Setting it as an environment variable would be best.

Installation

Run npm to add @infisical/sdk to your project.

$ npm install @infisical/sdk

Configuration

Import the SDK and create a client instance with your Machine Identity.

import { InfisicalClient, LogLevel } from "@infisical/sdk";

const client = new InfisicalClient({
    auth: {
      universalAuth: {
        clientId: "YOUR_CLIENT_ID",
        clientSecret: "YOUR_CLIENT_SECRET"
      }
    },
    logLevel: LogLevel.Error
});

Parameters

options

object

Show properties

clientId

string

deprecated

Your machine identity client ID.This field is deprecated and will be removed in future versions. Please use the auth.universalAuth.clientId field instead.

clientSecret

string

deprecated

Your machine identity client secret.This field is deprecated and will be removed in future versions. Please use the auth.universalAuth.clientSecret field instead.

accessToken

string

deprecated

An access token obtained from the machine identity login endpoint.This field is deprecated and will be removed in future versions. Please use the auth.accessToken field instead.

cacheTtl

number

default:"300"

Time-to-live (in seconds) for refreshing cached secrets. If manually set to 0, caching will be disabled, this is not recommended.

siteUrl

string

default:"https://app.infisical.com"

Your self-hosted absolute site URL including the protocol (e.g. https://app.infisical.com)

logLevel

enum

default:"Error"

The level of logs you wish to log The logs are derived from Rust, as we have written our base SDK in Rust.

auth

AuthenticationOptions

The authentication object to use for the client. This is required unless you’re using environment variables.

Authentication

The SDK supports a variety of authentication methods. The most common authentication method is Universal Auth, which uses a client ID and client secret to authenticate.

Universal Auth

Using environment variables

INFISICAL_UNIVERSAL_AUTH_CLIENT_ID - Your machine identity client ID.
INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET - Your machine identity client secret.

Using the SDK directly

const client = new InfisicalClient({
    auth: {
      universalAuth: {
        clientId: "YOUR_CLIENT_ID",
        clientSecret: "YOUR_CLIENT_SECRET"
      }
    }
});

GCP ID Token Auth

Please note that this authentication method will only work if you’re running your application on Google Cloud Platform. Please read more about this authentication method.

Using environment variables

INFISICAL_GCP_AUTH_IDENTITY_ID - Your Infisical Machine Identity ID.

Using the SDK directly

const client = new InfisicalClient({
    auth: {
      gcpIdToken: {
        identityId: "YOUR_IDENTITY_ID"
      }
    }
});

GCP IAM Auth

Using environment variables

INFISICAL_GCP_IAM_AUTH_IDENTITY_ID - Your Infisical Machine Identity ID.
INFISICAL_GCP_IAM_SERVICE_ACCOUNT_KEY_FILE_PATH - The path to your GCP service account key file.

Using the SDK directly

const client = new InfisicalClient({
    auth: {
      gcpIam: {
        identityId: "YOUR_IDENTITY_ID",
        serviceAccountKeyFilePath: "./path/to/your/service-account-key.json"
      }
    }
});

AWS IAM Auth

Please note that this authentication method will only work if you’re running your application on AWS. Please read more about this authentication method.

Using environment variables

INFISICAL_AWS_IAM_AUTH_IDENTITY_ID - Your Infisical Machine Identity ID.

Using the SDK directly

const client = new InfisicalClient({
    auth: {
      awsIam: {
        identityId: "YOUR_IDENTITY_ID"
      }
    }
});

Azure Auth

Please note that this authentication method will only work if you’re running your application on Azure. Please read more about this authentication method.

Using environment variables

INFISICAL_AZURE_AUTH_IDENTITY_ID - Your Infisical Machine Identity ID.

Using the SDK directly

const client = new InfisicalClient({
  auth: {
    azure: {
      identityId: "YOUR_IDENTITY_ID"
    }
  }
});

Kubernetes Auth

Please note that this authentication method will only work if you’re running your application on Kubernetes. Please read more about this authentication method.

Using environment variables

INFISICAL_KUBERNETES_IDENTITY_ID - Your Infisical Machine Identity ID.
INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH_ENV_NAME - The environment variable name that contains the path to the service account token. This is optional and will default to /var/run/secrets/kubernetes.io/serviceaccount/token.

Using the SDK directly

const client = new InfisicalClient({
  auth: {
    kubernetes: {
      identityId: "YOUR_IDENTITY_ID",
      serviceAccountTokenPathEnvName: "/var/run/secrets/kubernetes.io/serviceaccount/token" // Optional
    }
  }
});

Caching

To reduce the number of API requests, the SDK temporarily stores secrets it retrieves. By default, a secret remains cached for 5 minutes after it’s first fetched. Each time it’s fetched again, this 5-minute timer resets. You can adjust this caching duration by setting the “cacheTtl” option when creating the client.

Working with Secrets

client.listSecrets(options)

const secrets = await client.listSecrets({
    environment: "dev",
    projectId: "PROJECT_ID",
    path: "/foo/bar/",
    includeImports: false
});

Retrieve all secrets within the Infisical project and environment that client is connected to

Parameters

object

Show properties

environment

string

required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

projectId

string

required

The project ID where the secret lives in.

path

string

The path from where secrets should be fetched from.

attachToProcessEnv

boolean

default:"false"

Whether or not to set the fetched secrets to the process environment. If true, you can access the secrets like so process.env["SECRET_NAME"].

recursive

boolean

default:"false"

Whether or not to fetch secrets recursively from the specified path. Please note that there’s a 20-depth limit for recursive fetching.

expandSecretReferences

boolean

default:"true"

Whether or not to expand secret references in the fetched secrets. Read about secret reference

includeImports

false

default:"boolean"

Whether or not to include imported secrets from the current path. Read about secret import

client.getSecret(options)

const secret = await client.getSecret({
    environment: "dev",
    projectId: "PROJECT_ID",
    secretName: "API_KEY",
    path: "/",
    type: "shared"
});

Retrieve a secret from Infisical. By default, getSecret() fetches and returns a shared secret.

Parameters

object

Show properties

secretName

string

required

The key of the secret to retrieve.

projectId

string

required

The project ID where the secret lives in.

environment

string

required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

path

string

The path from where secret should be fetched from.

type

string

The type of the secret. Valid options are “shared” or “personal”. If not specified, the default value is “shared”.

client.createSecret(options)

const newApiKey = await client.createSecret({
    projectId: "PROJECT_ID",
    environment: "dev",
    secretName: "API_KEY",
    secretValue: "SECRET VALUE",
    path: "/",
    type: "shared"
});

Create a new secret in Infisical.

Parameters

object

Show properties

secretName

string

required

The key of the secret to create.

secretValue

string

required

The value of the secret.

projectId

string

required

The project ID where the secret lives in.

environment

string

required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

path

string

The path from where secret should be created.

type

string

The type of the secret. Valid options are “shared” or “personal”. If not specified, the default value is “shared”.

client.updateSecret(options)

const updatedApiKey = await client.updateSecret({
    secretName: "API_KEY",
    secretValue: "NEW SECRET VALUE",
    projectId: "PROJECT_ID",
    environment: "dev",
    path: "/",
    type: "shared"
});

Update an existing secret in Infisical.

Parameters

object

Show properties

secretName

string

required

The key of the secret to update.

secretValue

string

required

The new value of the secret.

projectId

string

required

The project ID where the secret lives in.

environment

string

required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

path

string

The path from where secret should be updated.

type

string

The type of the secret. Valid options are “shared” or “personal”. If not specified, the default value is “shared”.

client.deleteSecret(options)

const deletedSecret = await client.deleteSecret({
    secretName: "API_KEY",

    environment: "dev",
    projectId: "PROJECT_ID",
    path: "/",

    type: "shared"
});

Delete a secret in Infisical.

Parameters

object

Show properties

secretName

string

The key of the secret to update.

projectId

string

required

The project ID where the secret lives in.

environment

string

required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

path

string

The path from where secret should be deleted.

type

string

The type of the secret. Valid options are “shared” or “personal”. If not specified, the default value is “shared”.

Cryptography

Create a symmetric key

Create a base64-encoded, 256-bit symmetric key to be used for encryption/decryption.

const key = client.createSymmetricKey();

Returns (string)

key (string): A base64-encoded, 256-bit symmetric key, that can be used for encryption/decryption purposes.

Encrypt symmetric

const { iv, tag, ciphertext } = await client.encryptSymmetric({
    key: key,
    plaintext: "Infisical is awesome!",
})

Parameters

object

required

Show properties

plaintext

string

The plaintext you want to encrypt.

key

string

required

The symmetric key to use for encryption.

Returns (object)

tag (string): A base64-encoded, 128-bit authentication tag. iv (string): A base64-encoded, 96-bit initialization vector. ciphertext (string): A base64-encoded, encrypted ciphertext.

Decrypt symmetric

const decryptedString = await client.decryptSymmetric({
    key: key,
    iv: iv,
    tag: tag,
    ciphertext: ciphertext,
});

Parameters

object

required

Show properties

ciphertext

string

The ciphertext you want to decrypt.

key

string

required

The symmetric key to use for encryption.

string

required

The initialization vector to use for decryption.

tag

string

required

The authentication tag to use for decryption.

Returns (string)

plaintext (string): The decrypted plaintext.

SDK's

​Basic Usage

​Installation

​Configuration

​Parameters

​Authentication

​Universal Auth

​GCP ID Token Auth

​GCP IAM Auth

​AWS IAM Auth

​Azure Auth

​Kubernetes Auth

​Caching

​Working with Secrets

​client.listSecrets(options)

​Parameters

​client.getSecret(options)

​Parameters

​client.createSecret(options)

​client.updateSecret(options)

​Parameters

​client.deleteSecret(options)

​Cryptography

​Create a symmetric key

​Returns (string)

​Encrypt symmetric

​Parameters

​Returns (object)

​Decrypt symmetric

​Parameters

​Returns (string)

Basic Usage

Installation

Configuration

Parameters

Authentication

Universal Auth

GCP ID Token Auth

GCP IAM Auth

AWS IAM Auth

Azure Auth

Kubernetes Auth

Caching

Working with Secrets

client.listSecrets(options)

Parameters

client.getSecret(options)

Parameters

client.createSecret(options)

client.updateSecret(options)

Parameters

client.deleteSecret(options)

Cryptography

Create a symmetric key

Returns (string)

Encrypt symmetric

Parameters

Returns (object)

Decrypt symmetric

Parameters

Returns (string)