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

Basic usage

require "infisical"

client = Infisical::Client.new

# Authenticate with a machine identity
client.auth.universal_auth_login(
  client_id: ENV.fetch("INFISICAL_CLIENT_ID"),
  client_secret: ENV.fetch("INFISICAL_CLIENT_SECRET")
)

# Fetch a secret by name
secret = client.secrets.get(
  "API_KEY",
  project_id: "YOUR_PROJECT_ID",
  environment: "dev"
)

puts secret.secret_value

This example demonstrates how to use the Infisical Ruby SDK in a simple Ruby application. The application retrieves a secret named API_KEY from the dev environment of the YOUR_PROJECT_ID project.

We don’t recommend hardcoding your Machine Identity Tokens. Setting it as an environment variable would be best.

Installation

The SDK requires Ruby 3.0.0 or higher.

gem install infisical-sdk

Or add it to your Gemfile:

gem "infisical-sdk"

Configuration

Require the SDK and create a client instance. The require path is "infisical".

require "infisical"

client = Infisical::Client.new(
  site_url: "https://app.infisical.com" # Optional, defaults to https://app.infisical.com
)

Configuration options

object

Show properties

string

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

The URL of the Infisical instance. Set this to your instance URL when self-hosting Infisical.

integer

default:"10"

The timeout, in seconds, for HTTP requests made by the SDK.

Authentication

The SDK authenticates as a machine identity. The most common authentication method is Universal Auth, which uses a client ID and client secret. If you already have a valid access token, you can also set it on the client directly.

Universal auth

Log in with a machine identity’s client ID and client secret. On success, the returned access token is stored on the client and used for all subsequent requests.

client.auth.universal_auth_login(
  client_id: ENV.fetch("INFISICAL_CLIENT_ID"),
  client_secret: ENV.fetch("INFISICAL_CLIENT_SECRET")
)

Parameters

object

Show properties

string

required

The client ID of your machine identity.

string

required

The client secret of your machine identity.

Access token

If you already have a valid access token, set it on the client directly instead of logging in. This doesn’t make a network request.

client.auth.access_token("YOUR_ACCESS_TOKEN")

Parameters

string

required

The access token to authenticate with. This shouldn’t include the Bearer prefix.

Secrets

List secrets

client.secrets.list(options) Retrieve all secrets within a project and environment. Returns an array of secret objects sorted by key.

secrets = client.secrets.list(
  project_id: "YOUR_PROJECT_ID",
  environment: "dev",
  secret_path: "/"
)

Parameters

object

Show properties

string

required

The ID of the project where the secrets live.

string

required

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

string

default:"/"

The path from where secrets should be fetched.

boolean

default:"true"

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

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.

boolean

default:"false"

Whether or not to set the fetched secrets to the process environment (ENV). Only variables that are unset or empty are populated.

Retrieve secret

client.secrets.get(secret_name, options) Retrieve a single secret by name. Raises Infisical::NotFoundError if the secret doesn’t exist.

secret = client.secrets.get(
  "API_KEY",
  project_id: "YOUR_PROJECT_ID",
  environment: "dev"
)

Parameters

object

Show properties

string

required

The name of the secret to retrieve. Passed as the first positional argument.

string

required

The ID of the project where the secret lives.

string

required

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

string

default:"/"

The path from where the secret should be fetched.

boolean

default:"true"

Whether or not to include imported secrets when resolving the secret.

Create secret

client.secrets.create(secret_name, secret_value, options) Create a new secret. Returns the created secret.

secret = client.secrets.create(
  "API_KEY",
  "SECRET_VALUE",
  project_id: "YOUR_PROJECT_ID",
  environment: "dev"
)

Parameters

object

Show properties

string

required

The name of the secret to create. Passed as the first positional argument.

string

required

The value of the secret. Passed as the second positional argument.

string

required

The ID of the project where the secret will be created.

string

required

The slug name (dev, prod, etc.) of the environment where the secret will be created.

string

default:"/"

The path where the secret should be created.

string

A comment to associate with the secret.

boolean

Whether or not to skip multiline encoding for the secret value.

Update secret

client.secrets.update(secret_name, options) Update an existing secret’s value, rename it, or both. You must provide at least one of secret_value or new_secret_name, otherwise an ArgumentError is raised. Returns the updated secret.

secret = client.secrets.update(
  "API_KEY",
  project_id: "YOUR_PROJECT_ID",
  environment: "dev",
  secret_value: "UPDATED_SECRET_VALUE"
)

Parameters

object

Show properties

string

required

The name of the secret to update. Passed as the first positional argument.

string

required

The ID of the project where the secret lives.

string

required

The slug name (dev, prod, etc.) of the environment where the secret lives.

string

The new value of the secret. Required unless new_secret_name is provided.

string

A new name for the secret. Required unless secret_value is provided.

string

default:"/"

The path where the secret lives.

boolean

Whether or not to skip multiline encoding for the new secret value.

Delete secret

client.secrets.delete(secret_name, options) Delete a secret by name. Raises Infisical::NotFoundError if the secret doesn’t exist. Returns the deleted secret.

secret = client.secrets.delete(
  "API_KEY",
  project_id: "YOUR_PROJECT_ID",
  environment: "dev"
)

Parameters

object

Show properties

string

required

The name of the secret to delete. Passed as the first positional argument.

string

required

The ID of the project where the secret lives.

string

required

The slug name (dev, prod, etc.) of the environment where the secret lives.

string

default:"/"

The path where the secret lives.

The secret object

Every secret operation returns an Infisical::Models::Secret with the following readers:

object

Show properties

string

The name of the secret.

string

The value of the secret.

string

The comment associated with the secret.

string

The path the secret lives at.

string

The environment slug the secret belongs to.

string

The ID of the project the secret belongs to.

integer

The version number of the secret.

string

The secret type, either shared or personal.

string

The unique ID of the secret.

string

When the secret was created.

string

When the secret was last updated.

​Basic usage

​Installation

​Configuration

​Configuration options

​Authentication

​Universal auth

​Access token

​Secrets

​List secrets

​Retrieve secret

​Create secret

​Update secret

​Delete secret

​The secret object

Basic usage

Installation

Configuration

Configuration options

Authentication

Universal auth

Access token

Secrets

List secrets

Retrieve secret

Create secret

Update secret

Delete secret

The secret object