> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Infisical Ruby SDK

> Fetch and manage secrets in a Ruby application with the official Infisical Ruby SDK.

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.

* [Package](https://rubygems.org/gems/infisical-sdk)
* [GitHub Repository](https://github.com/Infisical/ruby-sdk)

# Basic usage

```ruby theme={"dark"}
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.

> [!WARNING]
>
> We don't recommend hardcoding your [Machine Identity
> Tokens](https://infisical.com/docs/documentation/platform/identities/machine-identities.md). Setting it as
> an environment variable would be best.

# Installation

The SDK requires Ruby 3.0.0 or higher.

```console theme={"dark"}
gem install infisical-sdk
```

Or add it to your Gemfile:

```ruby theme={"dark"}
gem "infisical-sdk"
```

# Configuration

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

```ruby theme={"dark"}
require "infisical"

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

### Configuration options

**options** `object`

**properties**

**site\_url** `string` (default: [https://app.infisical.com](https://app.infisical.com))

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

**timeout** `integer` (default: 10)

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

# Authentication

The SDK authenticates as a [machine identity](https://infisical.com/docs/documentation/platform/identities/machine-identities.md). 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.

```ruby theme={"dark"}
client.auth.universal_auth_login(
  client_id: ENV.fetch("INFISICAL_CLIENT_ID"),
  client_secret: ENV.fetch("INFISICAL_CLIENT_SECRET")
)
```

**Parameters**

**Parameters** `object`

**properties**

**client\_id** `string` *required*

The client ID of your machine identity.

**client\_secret** `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.

```ruby theme={"dark"}
client.auth.access_token("YOUR_ACCESS_TOKEN")
```

**Parameters**

**access\_token** `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.

```ruby theme={"dark"}
secrets = client.secrets.list(
  project_id: "YOUR_PROJECT_ID",
  environment: "dev",
  secret_path: "/"
)
```

**Parameters**

**Parameters** `object`

**properties**

**project\_id** `string` *required*

The ID of the project where the secrets live.

**environment** `string` *required*

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

**secret\_path** `string` (default: /)

The path from where secrets should be fetched.

**include\_imports** `boolean` (default: true)

Whether or not to include imported secrets from the current path. Read about [secret import](https://infisical.com/docs/documentation/platform/secret-reference.md).

**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.

**attach\_to\_process\_env** `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.

```ruby theme={"dark"}
secret = client.secrets.get(
  "API_KEY",
  project_id: "YOUR_PROJECT_ID",
  environment: "dev"
)
```

**Parameters**

**Parameters** `object`

**properties**

**secret\_name** `string` *required*

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

**project\_id** `string` *required*

The ID of the project where the secret lives.

**environment** `string` *required*

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

**secret\_path** `string` (default: /)

The path from where the secret should be fetched.

**include\_imports** `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.

```ruby theme={"dark"}
secret = client.secrets.create(
  "API_KEY",
  "SECRET_VALUE",
  project_id: "YOUR_PROJECT_ID",
  environment: "dev"
)
```

**Parameters**

**Parameters** `object`

**properties**

**secret\_name** `string` *required*

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

**secret\_value** `string` *required*

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

**project\_id** `string` *required*

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

**environment** `string` *required*

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

**secret\_path** `string` (default: /)

The path where the secret should be created.

**secret\_comment** `string`

A comment to associate with the secret.

**skip\_multiline\_encoding** `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.

```ruby theme={"dark"}
secret = client.secrets.update(
  "API_KEY",
  project_id: "YOUR_PROJECT_ID",
  environment: "dev",
  secret_value: "UPDATED_SECRET_VALUE"
)
```

**Parameters**

**Parameters** `object`

**properties**

**secret\_name** `string` *required*

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

**project\_id** `string` *required*

The ID of the project where the secret lives.

**environment** `string` *required*

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

**secret\_value** `string`

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

**new\_secret\_name** `string`

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

**secret\_path** `string` (default: /)

The path where the secret lives.

**skip\_multiline\_encoding** `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.

```ruby theme={"dark"}
secret = client.secrets.delete(
  "API_KEY",
  project_id: "YOUR_PROJECT_ID",
  environment: "dev"
)
```

**Parameters**

**Parameters** `object`

**properties**

**secret\_name** `string` *required*

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

**project\_id** `string` *required*

The ID of the project where the secret lives.

**environment** `string` *required*

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

**secret\_path** `string` (default: /)

The path where the secret lives.

### The secret object

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

**Secret** `object`

**properties**

**secret\_key** `string`

The name of the secret.

**secret\_value** `string`

The value of the secret.

**secret\_comment** `string`

The comment associated with the secret.

**secret\_path** `string`

The path the secret lives at.

**environment** `string`

The environment slug the secret belongs to.

**workspace** `string`

The ID of the project the secret belongs to.

**version** `integer`

The version number of the secret.

**type** `string`

The secret type, either `shared` or `personal`.

**id** `string`

The unique ID of the secret.

**created\_at** `string`

When the secret was created.

**updated\_at** `string`

When the secret was last updated.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.