awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1264 from Infisical/sdk/docs-update

Browse Source 
SDK documentation update
This commit is contained in:
vmatsiiako
2023-12-23 09:30:35 -08:00
committed by GitHub
parent a3739cfe50 026864951b
commit 6725475575
8 changed files with 684 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/sdks/languages/go.mdx
View File

@@ -5,5 +5,4 @@ icon: "golang"
Coming soon.
Follow this GitHub
[issue](https://github.com/Infisical/infisical/issues/436) to stay updated.
Star our GitHub repository to stay updated [cross-language SDK](https://github.com/Infisical/sdk) GitHub repository to stay updated.

292
docs/sdks/languages/java.mdx
View File

@@ -3,7 +3,293 @@ title: "Java"
icon: "java"
---
Coming soon.
If you're working with Java, the official [Infisical Java SDK](https://github.com/Infisical/sdk/tree/main/languages/java) package is the easiest way to fetch and work with secrets for your application.
Follow this GitHub
[issue](https://github.com/Infisical/infisical/issues/434) to stay updated.
## Basic Usage
```java
package com.example.app;
import com.infisical.sdk.InfisicalClient;
import com.infisical.sdk.schema.*;
public class Example {
public static void main(String[] args) {
// Create a new Infisical Client
ClientSettings settings = new ClientSettings();
settings.setClientID("MACHINE_IDENTITY_CLIENT_ID");
settings.setClientSecret("MACHINE_IDENTITY_CLIENT_SECRET");
InfisicalClient client = new InfisicalClient(settings);
// Create the options for fetching the secret
GetSecretOptions options = new GetSecretOptions();
options.setSecretName("TEST");
options.setEnvironment("dev");
options.setProjectID("PROJECT_ID");
// Fetch the sercret with the provided options
GetSecretResponseSecret secret = client.getSecret(options);
// Print the value
System.out.println(secret.getSecretValue());
// Important to avoid memory leaks!
// If you intend to use the client throughout your entire application, you can omit this line.
client.close();
}
}
```
This example demonstrates how to use the Infisical Java SDK in a Java application. The application retrieves a secret named `TEST` from the `dev` environment of the `PROJECT_ID` project.
<Warning>
We do not recommend hardcoding your [Machine Identity Tokens](/platform/identities/overview). Setting it as an environment variable would be best.
</Warning>
# Installation
The Infisical Java SDK is hosted on the GitHub Packages Apache Maven registry. Because of this you need to configure your environment properly so it's able to pull dependencies from the GitHub registry. Please check [this guide from GitHub](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) on how to achieve this.
Our package is [located here](https://github.com/Infisical/sdk/packages/2019741). Please follow the installation guide on the page.
# Configuration
Import the SDK and create a client instance with your [Machine Identity](/platform/identities/universal-auth).
```java
import com.infisical.sdk.InfisicalClient;
import com.infisical.sdk.schema.*;
public class App {
public static void main(String[] args) {
ClientSettings settings = new ClientSettings();
settings.setClientID("MACHINE_IDENTITY_CLIENT_ID");
settings.setClientSecret("MACHINE_IDENTITY_CLIENT_SECRET");
InfisicalClient client = new InfisicalClient(settings); // Your client!
}
}
```
### ClientSettings methods
<ParamField query="options" type="object">
<Expandable title="properties">
<ParamField query="setClientID()" type="string" optional>
Your machine identity client ID.
</ParamField>
<ParamField query="setClientSecret()" type="string" optional>
Your machine identity client secret.
</ParamField>
<ParamField query="setAccessToken()" type="string" optional>
An access token obtained from the machine identity login endpoint.
</ParamField>
<ParamField query="setSiteURL()" type="string" default="https://app.infisical.com" optional>
Your self-hosted absolute site URL including the protocol (e.g. `https://app.infisical.com`)
</ParamField>
</Expandable>
</ParamField>
## Working with Secrets
### client.listSecrets(options)
```java
ListSecretsOptions options = new ListSecretsOptions();
options.setEnvironment("dev");
options.setProjectID("PROJECT_ID");
options.setPath("/foo/bar");
options.setIncludeImports(false);
SecretElement[] secrets = client.listSecrets(options);
```
Retrieve all secrets within the Infisical project and environment that client is connected to
### Methods
<ParamField query="Parameters" type="object">
<Expandable title="properties">
<ParamField query="setEnvironment()" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="setProjectID()" type="string">
The project ID where the secret lives in.
</ParamField>
<ParamField query="setPath()" type="string" optional>
The path from where secrets should be fetched from.
</ParamField>
<ParamField query="setIncludeImports" type="string" default="https://app.infisical.com" optional>
Whether or not to include imported secrets from the current path. Read about [secret import](/documentation/platform/secret-reference)
</ParamField>
</Expandable>
</ParamField>
### client.getSecret(options)
```java
GetSecretOptions options = new GetSecretOptions();
options.setSecretName("TEST");
options.setEnvironment("dev");
options.setProjectID("PROJECT_ID");
GetSecretResponseSecret secret = client.getSecret(options);
String secretValue = secret.getSecretValue();
```
Retrieve a secret from Infisical.
By default, `getSecret()` fetches and returns a shared secret.
### Methods
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="setSecretName()" type="string" required>
The key of the secret to retrieve.
</ParamField>
<ParamField query="setProjectID()" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="setEnvironment()" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="setPath()" type="string" optional>
The path from where secret should be fetched from.
</ParamField>
<ParamField query="setType()" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
### client.createSecret(options)
```java
CreateSecretOptions createOptions = new CreateSecretOptions();
createOptions.setSecretName("NEW_SECRET");
createOptions.setEnvironment("dev");
createOptions.setProjectID("PROJECT_ID");
createOptions.setSecretValue("SOME SECRET VALUE");
createOptions.setPath("/"); // Default
createOptions.setType("shared"); // Default
CreateSecretResponseSecret newSecret = client.createSecret(createOptions);
```
Create a new secret in Infisical.
### Methods
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="setSecretName()" type="string" required>
The key of the secret to create.
</ParamField>
<ParamField query="setSecretValue()" type="string" required>
The value of the secret.
</ParamField>
<ParamField query="setProjectID()" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="setEnvironment()" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="setPath()" type="string" optional>
The path from where secret should be created.
</ParamField>
<ParamField query="setType()" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
### client.updateSecret(options)
```java
UpdateSecretOptions options = new UpdateSecretOptions();
options.setSecretName("SECRET_TO_UPDATE");
options.setSecretValue("NEW SECRET VALUE");
options.setEnvironment("dev");
options.setProjectID("PROJECT_ID");
options.setPath("/"); // Default
options.setType("shared"); // Default
UpdateSecretResponseSecret updatedSecret = client.updateSecret(options);
```
Update an existing secret in Infisical.
### Methods
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="setSecretName()" type="string" required>
The key of the secret to update.
</ParamField>
<ParamField query="setSecretValue()" type="string" required>
The new value of the secret.
</ParamField>
<ParamField query="setProjectID()" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="setEnvironment()" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="setPath()" type="string" optional>
The path from where secret should be updated.
</ParamField>
<ParamField query="setType()" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
### client.deleteSecret(options)
```java
DeleteSecretOptions options = new DeleteSecretOptions();
options.setSecretName("SECRET_TO_DELETE");
options.setEnvironment("dev");
options.setProjectID("PROJECT_ID");
options.setPath("/"); // Default
options.setType("shared"); // Default
DeleteSecretResponseSecret deletedSecret = client.deleteSecret(options);
```
Delete a secret in Infisical.
### Methods
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="setSecretName()" type="string">
The key of the secret to update.
</ParamField>
<ParamField query="setProjectID()" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="setEnvironment()" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="setPath()" type="string" optional>
The path from where secret should be deleted.
</ParamField>
<ParamField query="setType()" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>

308
docs/sdks/languages/node.mdx
View File

@@ -3,205 +3,301 @@ title: "Node"
icon: "node"
---
If you're working with Node.js, the official [infisical-node](https://github.com/Infisical/infisical-node) package is the easiest way to fetch and work with secrets for your application.
If you're working with Node.js, the official [infisical-node](https://github.com/Infisical/sdk/tree/main/languages/node) package is the easiest way to fetch and work with secrets for your application.
## Basic Usage
```js
import express from "express";
import InfisicalClient from "infisical-node";
import { InfisicalClient, LogLevel } from "@infisical/sdk";
const app = express();
const PORT = 3000;
const client = new InfisicalClient({
token: "YOUR_INFISICAL_TOKEN"
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET",
logLevel: LogLevel.Error
});
app.get("/", async (req, res) => {
// access value
const name = await client.getSecret("NAME");
res.send(`Hello! My name is: ${name.secretValue}`);
// access value
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 () => {
console.log(`App listening on port ${PORT}`);
// 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.
<Warning>
We do not recommend hardcoding your [Infisical
Token](/documentation/platform/token). Setting it as an environment
variable would be best.
We do not recommend hardcoding your [Machine Identity Tokens](/documentation/platform/identities/overview). Setting it as an environment variable
would be best.
</Warning>
## Installation
Run `npm` to add `infisical-node` to your project.
Run `npm` to add `@infisical/sdk` to your project.
```console
$ npm install infisical-node --save
$ npm install @infisical/sdk
```
## Configuration
Import the SDK and create a client instance with your [Infisical Token](/documentation/platform/token).
Import the SDK and create a client instance with your [Machine Identity](/documentation/platform/identities/overview).
<Tabs>
<Tab title="ES6">
```js
import InfisicalClient from "infisical-node";
import { InfisicalClient, LogLevel } from "@infisical/sdk";
const client = new InfisicalClient({
token: "your_infisical_token"
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET",
logLevel: LogLevel.Error
});
```
</Tab>
<Tab title="ES5">
```js
const InfisicalClient = require("infisical-node");
const { InfisicalClient, LogLevel } = require("@infisical/sdk");
const client = new InfisicalClient({
token: "your_infisical_token"
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET",
logLevel: LogLevel.Error
});
````
</Tab>
</Tab>
</Tabs>
### Parameters
<ParamField query="options" type="object">
<Expandable title="properties">
<ParamField query="token" type="string" optional>
An [Infisical Token](/documentation/platform/token) scoped to a project
and environment
</ParamField>
<ParamField
query="siteURL"
type="string"
default="https://app.infisical.com"
optional
>
Your self-hosted absolute site URL including the protocol (e.g.
`https://app.infisical.com`)
</ParamField>
<ParamField query="cacheTTL" type="number" default="300" optional>
Time-to-live (in seconds) for refreshing cached secrets. Default: `300`.
</ParamField>
<ParamField query="debug" type="boolean" default="false" optional>
Whether or not debug mode is on
</ParamField>
</Expandable>
<Expandable title="properties">
<ParamField query="clientId" type="string" optional>
Your machine identity client ID.
</ParamField>
<ParamField query="clientSecret" type="string" optional>
Your machine identity client secret.
</ParamField>
<ParamField query="accessToken" type="string" optional>
An access token obtained from the machine identity login endpoint.
</ParamField>
<ParamField query="siteUrl" type="string" default="https://app.infisical.com" optional>
Your self-hosted absolute site URL including the protocol (e.g. `https://app.infisical.com`)
</ParamField>
<ParamField query="logLevel" type="enum" default="Error" optional>
The level of logs you wish to log The logs are derived from Rust, as we have written our base SDK in Rust.
</ParamField>
</Expandable>
</ParamField>
## Caching
The SDK caches every secret and updates it periodically based on the provided `cacheTTL`. For example, if `cacheTTL` of `300` is provided, then a secret will be refetched 5 minutes after the first fetch; if the fetch fails, the cached secret is returned.
<Tip>
For optimal performance, we recommend creating a single instance of the Infisical client and exporting it to be used across your entire app to take advantage of caching benefits.
</Tip>
## Working with Secrets
### client.getAllSecrets()
### client.listSecrets(options)
```js
const secrets = await client.getAllSecrets();
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
### client.getSecret(secretName, options)
### Parameters
<ParamField query="Parameters" type="object">
<Expandable title="properties">
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="projectId" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secrets should be fetched from.
</ParamField>
<ParamField query="includeImports" type="string" default="https://app.infisical.com" optional>
Whether or not to include imported secrets from the current path. Read about [secret import](/documentation/platform/secret-reference)
</ParamField>
</Expandable>
</ParamField>
### client.getSecret(options)
```js
const secret = await client.getSecret("API_KEY");
const value = secret.secretValue; // get its value
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 personal secret. If not found, it returns a shared secret, or tries to retrieve the value from `process.env`. If a secret is fetched, `getSecret()` caches it to reduce excessive calls and re-fetches periodically based on the `cacheTTL` option (default is `300` seconds) when initializing the client — for more information, see the caching section.
By default, `getSecret()` fetches and returns a shared secret.
### Parameters
<ParamField query="secretName" type="string" required>
The key of the secret to retrieve
</ParamField>
<ParamField query="options" type="object" optional>
<Expandable title="properties">
<ParamField query="type" type="string" default="personal" optional>
The type of the secret. Valid options are "shared" or "personal"
</ParamField>
</Expandable>
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="secretName" type="string" required>
The key of the secret to retrieve.
</ParamField>
<ParamField query="projectId" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secret should be fetched from.
</ParamField>
<ParamField query="type" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
### client.createSecret(secretName, secretValue, options)
### client.createSecret(options)
```js
const newApiKey = await client.createSecret("API_KEY", "FOO");
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.
<ParamField query="secretName" type="string" required>
The key of the secret to create
</ParamField>
<ParamField query="secretName" type="string" required>
The value of the secret to create
</ParamField>
<ParamField query="options" type="object" default="object" optional>
<Expandable title="properties">
<ParamField query="type" type="string" default="shared" optional>
The type of the secret. Valid options are "shared" or "personal". A personal secret can only be created if a shared secret with the same name exists.
</ParamField>
</Expandable>
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="secretName" type="string" required>
The key of the secret to create.
</ParamField>
<ParamField query="secretValue" type="string" required>
The value of the secret.
</ParamField>
<ParamField query="projectId" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secret should be created.
</ParamField>
<ParamField query="type" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
### client.updateSecret(secretName, secretValue, options)
### client.updateSecret(options)
```js
const updatedApiKey = await client.updateSecret("API_KEY", "BAR");
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
<ParamField query="secretName" type="string" required>
The key of the secret to update
</ParamField>
<ParamField query="secretName" type="string" required>
The new value of the secret
</ParamField>
<ParamField query="options" type="object" default="object" optional>
<Expandable title="properties">
<ParamField query="type" type="string" default="shared" optional>
The type of the secret. Valid options are "shared" or "personal"
</ParamField>
</Expandable>
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="secretName" type="string" required>
The key of the secret to update.
</ParamField>
<ParamField query="secretValue" type="string" required>
The new value of the secret.
</ParamField>
<ParamField query="projectId" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secret should be updated.
</ParamField>
<ParamField query="type" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
### client.deleteSecret(secretName, options)
### client.deleteSecret(options)
```js
const deletedSecret = await client.deleteSecret("API_KEY");
const deletedSecret = await client.deleteSecret({
secretName: "API_KEY",
environment: "dev",
projectId: "PROJECT_ID",
path: "/",
type: "shared"
});
```
Delete a secret in Infisical.
<ParamField query="secretName" type="string" required>
The key of the secret to delete
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="secretName" type="string">
The key of the secret to update.
</ParamField>
<ParamField query="projectId" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secret should be deleted.
</ParamField>
<ParamField query="type" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
<ParamField query="options" type="object" default="object" optional>
<Expandable title="properties">
<ParamField query="type" type="string" default="shared" optional>
The type of the secret. Valid options are "shared" or "personal". Note that deleting a shared secret also deletes all associated personal secrets.
</ParamField>
</Expandable>
</ParamField>

2
docs/sdks/languages/php.mdx
View File

@@ -5,4 +5,4 @@ icon: "php"
Coming soon.
Follow this GitHub [issue](https://github.com/Infisical/infisical/issues/531) to stay updated.
Star our GitHub repository to stay updated [cross-language SDK](https://github.com/Infisical/sdk) GitHub repository to stay updated.

232
docs/sdks/languages/python.mdx
View File

@@ -3,31 +3,38 @@ title: "Python"
icon: "python"
---
If you're working with Python, the official [infisical-python](https://github.com/Infisical/infisical-python) package is the easiest way to fetch and work with secrets for your application.
If you're working with Python, the official [infisical-python](https://github.com/Infisical/sdk/edit/main/crates/infisical-py) package is the easiest way to fetch and work with secrets for your application.
## Basic Usage
```py
from flask import Flask
from infisical import InfisicalClient
from infisical_client import ClientSettings, InfisicalClient, GetSecretOptions
app = Flask(__name__)
client = InfisicalClient(token="your_infisical_token")
client = InfisicalClient(ClientSettings(
client_id="MACHINE_IDENTITY_CLIENT_ID",
client_secret="MACHINE_IDENTITY_CLIENT_SECRET",
))
@app.route("/")
def hello_world():
# access value
name = client.get_secret("NAME")
name = client.getSecret(options=GetSecretOptions(
environment="dev",
project_id="PROJECT_ID",
secret_name="NAME"
))
return f"Hello! My name is: {name.secret_value}"
```
This example demonstrates how to use the Infisical Python SDK with a Flask application. The application retrieves a secret named "NAME" and responds to requests with a greeting that includes the secret value.
<Warning>
We do not recommend hardcoding your [Infisical
Token](/documentation/platform/token). Setting it as an environment
variable would be best.
We do not recommend hardcoding your [Machine Identity Tokens](/platform/identities/overview). Setting it as an environment variable would be best.
</Warning>
## Installation
@@ -35,26 +42,34 @@ This example demonstrates how to use the Infisical Python SDK with a Flask appli
Run `pip` to add `infisical-python` to your project
```console
$ pip install infisical
$ pip install infisical-python
```
Note: You need Python 3.7+.
## Configuration
Import the SDK and create a client instance with your [Infisical Token](/documentation/platform/token).
Import the SDK and create a client instance with your [Machine Identity](/api-reference/overview/authentication).
```py
from infisical import InfisicalClient
from infisical_client import ClientSettings, InfisicalClient
client = InfisicalClient(token="your_infisical_token")
client = InfisicalClient(ClientSettings(
client_id="MACHINE_IDENTITY_CLIENT_ID",
client_secret="MACHINE_IDENTITY_CLIENT_SECRET",
))
```
### Parameters
<ParamField query="token" type="string" optional>
An [Infisical Token](/documentation/platform/token) scoped to a project
and environment
<ParamField query="client_id" type="string" optional>
Your Infisical Client ID.
</ParamField>
<ParamField query="client_secret" type="string" optional>
Your Infisical Client Secret.
</ParamField>
<ParamField query="access_token" type="string" optional>
If you want to directly pass an access token obtained from the authentication endpoints, you can do so.
</ParamField>
<ParamField
query="site_url"
@@ -65,105 +80,186 @@ client = InfisicalClient(token="your_infisical_token")
Your self-hosted absolute site URL including the protocol (e.g.
`https://app.infisical.com`)
</ParamField>
<ParamField query="cache_ttl" type="number" default="300" optional>
Time-to-live (in seconds) for refreshing cached secrets. Default: `300`.
</ParamField>
<ParamField query="debug" type="boolean" default="false" optional>
Whether or not debug mode is on
</ParamField>
## Caching
The SDK caches every secret and updates it periodically based on the provided `cache_ttl`. For example, if `cache_ttl` of `300` is provided, then a secret will be refetched 5 minutes after the first fetch; if the fetch fails, the cached secret is returned.
<Tip>
For optimal performance, we recommend creating a single instance of the Infisical client and exporting it to be used across your entire app to take advantage of caching benefits.
</Tip>
## Working with Secrets
### client.get_all_secrets()
### client.listSecrets(options)
```py
secrets = client.get_all_secrets()
client.listSecrets(options=ListSecretsOptions(
environment="dev",
project_id="PROJECT_ID"
))
```
Retrieve all secrets within the Infisical project and environment that client is connected to
### client.get_secret(secret_name, options)
### Parameters
<ParamField query="Parameters" type="object">
<Expandable title="properties">
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="project_id" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secrets should be fetched from.
</ParamField>
<ParamField query="include_imports" type="string" default="https://app.infisical.com" optional>
Whether or not to include imported secrets from the current path. Read about [secret import](/documentation/platform/secret-reference)
</ParamField>
</Expandable>
</ParamField>
### client.getSecret(options)
```py
secret = client.get_secret("API_KEY")
secret = client.getSecret(options=GetSecretOptions(
environment="dev",
project_id="PROJECT_ID",
secret_name="API_KEY"
))
value = secret.secret_value # get its value
```
By default, `get_secret()` fetches and returns a personal secret. If not found, it returns a shared secret, or tries to retrieve the value from `os.environ`. If a secret is fetched, `get_secret()` caches it to reduce excessive calls and re-fetches periodically based on the `cacheTTL` option (default is 300 seconds) when initializing the client — for more information, see the caching section.
By default, `getSecret()` fetches and returns a shared secret. If not found, it returns a personal secret.
### Parameters
<ParamField query="secret_name" type="string" required>
The key of the secret to retrieve
</ParamField>
<ParamField query="type" type="string" default="personal" optional>
The type of the secret. Valid options are "shared" or "personal"
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="secret_name" type="string" required>
The key of the secret to retrieve
</ParamField>
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="project_id" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secret should be fetched from.
</ParamField>
<ParamField query="type" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "personal".
</ParamField>
<ParamField query="include_imports" type="string" default="https://app.infisical.com" optional>
Whether or not to include imported secrets from the current path. Read about [secret import](/documentation/platform/secret-reference)
</ParamField>
</Expandable>
</ParamField>
### client.create_secret(secret_name, secret_value, options)
### client.createSecret(options)
```py
new_api_key = client.create_secret("API_KEY", "FOO");
api_key = client.createSecret(options=CreateSecretOptions(
secret_name="API_KEY",
secret_value="Some API Key",
environment="dev",
project_id="PROJECT_ID"
))
```
Create a new secret in Infisical.
### Parameters
<ParamField query="secret_name" type="string" required>
The key of the secret to create
</ParamField>
<ParamField query="secret_value" type="string" required>
The value of the secret to create
</ParamField>
<ParamField query="type" type="string" default="shared" optional>
The type of the secret. Valid options are "shared" or "personal". A personal secret can only be created if a shared secret with the same name exists.
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="secret_name" type="string" required>
The key of the secret to create.
</ParamField>
<ParamField query="secret_value" type="string" required>
The value of the secret.
</ParamField>
<ParamField query="project_id" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secret should be created.
</ParamField>
<ParamField query="type" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
### client.update_secret(secret_name, secret_value, options)
### client.updateSecret(options)
```py
updated_api_key = client.update_secret("API_KEY", "BAR");
client.updateSecret(options=UpdateSecretOptions(
secret_name="API_KEY",
secret_value="NEW_VALUE",
environment="dev",
project_id="PROJECT_ID"
))
```
Update an existing secret in Infisical.
### Parameters
<ParamField query="secret_name" type="string" required>
The key of the secret to update
</ParamField>
<ParamField query="secret_value" type="string" required>
The new value of the secret
</ParamField>
<ParamField query="type" type="string" default="shared" optional>
The type of the secret. Valid options are "shared" or "personal"
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="secret_name" type="string" required>
The key of the secret to update.
</ParamField>
<ParamField query="secret_value" type="string" required>
The new value of the secret.
</ParamField>
<ParamField query="project_id" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secret should be updated.
</ParamField>
<ParamField query="type" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
### client.delete_secret(secret_name, options)
### client.deleteSecret(options)
```py
deleted_secret = client.delete_secret("API_KEY");
client.deleteSecret(options=DeleteSecretOptions(
environment="dev",
project_id="PROJECT_ID",
secret_name="API_KEY"
))
```
Delete a secret in Infisical.
### Parameters
<ParamField query="secret_name" type="string" required>
The key of the secret to delete
<ParamField query="Parameters" type="object" optional>
<Expandable title="properties">
<ParamField query="secret_name" type="string">
The key of the secret to update.
</ParamField>
<ParamField query="project_id" type="string" required>
The project ID where the secret lives in.
</ParamField>
<ParamField query="environment" type="string" required>
The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
</ParamField>
<ParamField query="path" type="string" optional>
The path from where secret should be deleted.
</ParamField>
<ParamField query="type" type="string" optional>
The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
</ParamField>
</Expandable>
</ParamField>
<ParamField query="type" type="string" default="shared" optional>
The type of the secret. Valid options are "shared" or "personal"
</ParamField>
Follow this GitHub
[issue](https://github.com/Infisical/infisical/issues/433) to stay updated.

3
docs/sdks/languages/ruby.mdx
View File

@@ -5,5 +5,4 @@ icon: "gem"
Coming soon.
Follow this GitHub
[issue](https://github.com/Infisical/infisical/issues/435) to stay updated.
Star our GitHub repository to stay updated [cross-language SDK](https://github.com/Infisical/sdk) GitHub repository to stay updated.

3
docs/sdks/languages/rust.mdx
View File

@@ -5,5 +5,4 @@ icon: "rust"
Coming soon.
Follow this GitHub
[issue](https://github.com/Infisical/infisical/issues/437) to stay updated.
Star our GitHub repository to stay updated [cross-language SDK](https://github.com/Infisical/sdk) GitHub repository to stay updated.

122
docs/sdks/overview.mdx
View File

@@ -2,104 +2,32 @@
title: "Introduction"
---
From local development to production, Infisical SDKs provide the easiest way for your app to fetch back secrets from Infisical on demand.
From local development to production, Infisical SDKs provide the easiest way for your app to fetch back secrets from Infisical on demand.
- Install and initialize a language-specific client SDK into your application
- Provision the client scoped-access to a project and environment in Infisical
- Fetch secrets on demand
- Install and initialize a language-specific client SDK into your application
- Provision the client scoped-access to a project and environment in Infisical
- Fetch secrets on demand
<CardGroup cols={2}>
<Card
title="Node"
href="https://github.com/Infisical/sdk/tree/main/languages/node"
icon="node"
color="#68a063"
>
Manage secrets for your Node application on demand
</Card>
<Card
href="https://github.com/Infisical/sdk/tree/main/crates/infisical-py"
title="Python"
icon="python"
color="#4c8abe"
>
Manage secrets for your Python application on demand
</Card>
<Card
href="https://github.com/Infisical/sdk/tree/main/languages/java"
title="Java"
icon="java"
color="#e41f23"
>
Manage secrets for your Java application on demand
</Card>
<Card
href="/sdks/languages/ruby"
title="Ruby"
icon="gem"
color="#ac0d01"
>
Manage secrets for your Ruby application on demand
</Card>
<Card
href="/sdks/languages/go"
title="Golang"
icon="golang"
color="#00add8"
>
Manage secrets for your Go application on demand
</Card>
<Card
href="/sdks/languages/rust"
title="Rust"
icon="rust"
color="#cd412b"
>
Manage secrets for your Rust application on demand
</Card>
<Card
href="/sdks/languages/php"
title="PHP"
icon="php"
color="#787cb4"
>
Manage secrets for your PHP application on demand
</Card>
<Card title="Node" href="/sdks/languages/node" icon="node" color="#68a063">
Manage secrets for your Node application on demand
</Card>
<Card href="/sdks/languages/python" title="Python" icon="python" color="#4c8abe">
Manage secrets for your Python application on demand
</Card>
<Card href="/sdks/languages/java" title="Java" icon="java" color="#e41f23">
Manage secrets for your Java application on demand
</Card>
<Card href="/sdks/languages/ruby" title="Ruby" icon="gem" color="#ac0d01">
Manage secrets for your Ruby application on demand
</Card>
<Card href="/sdks/languages/go" title="Golang" icon="golang" color="#00add8">
Manage secrets for your Go application on demand
</Card>
<Card href="/sdks/languages/rust" title="Rust" icon="rust" color="#cd412b">
Manage secrets for your Rust application on demand
</Card>
<Card href="/sdks/languages/php" title="PHP" icon="php" color="#787cb4">
Manage secrets for your PHP application on demand
</Card>
</CardGroup>
## FAQ
<AccordionGroup>
<Accordion title="Are my secrets exposed in transit every time the SDK fetches them?">
No. Infisical uses end-to-end encryption which ensures that secrets are always encrypted in transit
and decrypted on the client side. In fact, not even the server can decrypt your secrets (unless
that permission is explicitly granted from within the platform).
Check out the [security guide](/security/overview).
</Accordion>
<Accordion title="Isn't it inefficient if my app makes a request every time it needs a secret?">
The client SDK caches every secret and implements a 5-minute waiting period before
re-requesting it. The waiting period can be controlled by setting the `cacheTTL` parameter at
the time of initializing the client.
</Accordion>
<Accordion title="What if a request for a secret fails?">
The SDK caches every secret and falls back to the cached value if a request fails. If no cached
value ever-existed, the SDK falls back to whatever value is on `process.env`.
</Accordion>
<Accordion title="Can I still use process.env with the SDK?">
Yes. If no `token` parameter is passed in at the time of initializing the client or nothing is found when requesting for a secret,
then the SDK falls back to whatever value is on `process.env`.
</Accordion>
<Accordion title="What's the point if I still have to manage a token for the SDK?">
The token enables the SDK to authenticate with Infisical to fetch back your secrets.
Although the SDK requires you to pass in a token, it enables greater efficiency and security
than if you managed dozens of secrets yourself without it. Here're some benefits:
- You always pull in the right secrets because they're fetched on demand from a centralize source that is Infisical.
- You can use the Infisical which comes with tons of benefits like secret versioning, access controls, audit logs, etc.
- You now risk leaking one token that can be revoked instead of dozens of raw secrets.
And much more.
</Accordion>
</AccordionGroup>