Update getting started guide for fetching secrets via API

2026-01-10 07:58:15 -05:00 · 2023-12-12 17:59:56 +07:00
parent b551ee50e7
commit 6cda14328b
7 changed files with 112 additions and 43 deletions
--- a/docs/api-reference/overview/authentication.mdx
+++ b/docs/api-reference/overview/authentication.mdx
@@ -8,7 +8,7 @@ You can authenticate with the Infisical API using [Identities](/documentation/pl
 In the following steps, we explore how to create an identity representing a workload or application to access the Infisical API.

 <Steps>
-  <Step title="Creating an identity">
+  <Step title="Create an identity">
    To create an identity, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**.

    ![identities organization](../../images/platform/identities/identities-org.png)
@@ -22,7 +22,7 @@ In the following steps, we explore how to create an identity representing a work
    ![identities organization create auth method](../../images/platform/identities/identities-org-create-auth-method.png)

  </Step>
-  <Step title="Creating a Client Secret">
+  <Step title="Create a Client Secret">
    In order to use the identity, you'll need the non-sensitive **Client ID**
    of the identity and a **Client Secret** for it; you can think of these credentials akin to a username
    and password used to authenticate with the Infisical API. With that, press on the key icon on the identity to generate a **Client Secret**
@@ -32,7 +32,7 @@ In the following steps, we explore how to create an identity representing a work
    ![identities client secret create](../../images/platform/identities/identities-org-client-secret-create-1.png)
    ![identities client secret create](../../images/platform/identities/identities-org-client-secret-create-2.png)
  </Step>
-  <Step title="Adding an identity to a project">
+  <Step title="Add an identity to a project">
    To enable the identity to access project-level resources such as secrets within a specific project, you should add it to that project.

    To do this, head over to the project you want to add the identity to and go to Project Settings > Access Control > Machine Identities and press **Add identity**.
@@ -43,7 +43,7 @@ In the following steps, we explore how to create an identity representing a work
    
    ![identities project create](../../images/platform/identities/identities-project-create.png)
  </Step>
-  <Step title="Accessing the Infisical API with the identity">
+  <Step title="Access the Infisical API with the identity">
    To access the Infisical API as the identity, you should first perform a login operation
    that is to exchange the **Client ID** and **Client Secret** of the identity for an access token
    by making a request to the `/api/v1/auth/universal-auth/login` endpoint.
--- a/docs/documentation/getting-started/api.mdx
+++ b/docs/documentation/getting-started/api.mdx
@@ -2,58 +2,127 @@
 title: "REST API"
 ---

-Infisical's Public (REST) API is the most flexible, platform-agnostic way to read/write secrets for your application.
+Infisical's REST API is the most flexible way to read/write secrets for your application.

-Prerequisites:
+In this brief, we'll explore how to fetch a secret back from a project on [Infisical Cloud](https://app.infisical.com) via the REST API.

- Have a project with secrets ready in [Infisical Cloud](https://app.infisical.com).
- Create an [Infisical Token](/documentation/platform/token) scoped to an environment in your project in Infisical.
+<Steps>
+    <Step title="Create a project with a secret">
+        To create a project, head to your Organization Overview and press **Add New Project**; we'll call the project **Demo App**.
+        ![create project](../../images/getting-started/api/org-create-project-1.png)
+        
+        ![create project](../../images/getting-started/api/org-create-project-2.png)
+        
+        Next, let's head to the **Development** environment of the project and add a secret `FOO=BAR` to it.
+        
+        ![explore project env](../../images/getting-started/api/project-explore-env.png)
+        
+        ![create secret](../../images/getting-started/api/project-create-secret.png)
+        
+        ![project dashboard](../../images/getting-started/api/project-dashboard.png)

-To keep it simple, we're going to fetch secrets from the API with **End-to-End Encryption (E2EE)** disabled.
+        <Note>
+            For this brief, you'll need to disable end-to-end encryption in your Project Settings
+        </Note>
+    </Step>
+    <Step title="Create an identity">
+        Next, we need to create an identity to represent your application. To create one, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**.

-<Note>
-    It's possible to use the API with **E2EE** enabled but this means learning about how encryption works with Infisical and performing client-side encryption/decryption operations yourself.
-    yourself. 
-    
-    If **E2EE** is a must for your team, we recommend either using one of the [Infisical SDKs](/documentation/getting-started/sdks) or checking out the [examples for E2EE](/api-reference/overview/examples/e2ee-disabled).
-</Note>
+        ![identities organization](../../images/platform/identities/identities-org.png)
+        
+        When creating an identity, you specify an organization level [role](/documentation/platform/role-based-access-controls) for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles.
+        
+        ![identities organization create](../../images/platform/identities/identities-org-create.png)
+        
+        Once you've created an identity, you'll be prompted to configure the **Universal Auth** authentication method for it.
+        
+        ![identities organization create auth method](../../images/platform/identities/identities-org-create-auth-method.png)

-## Configuration
+    </Step>
+    <Step title="Create a Client Secret">
+        In order to use the identity, you'll need the non-sensitive **Client ID**
+        of the identity and a **Client Secret** for it; you can think of these credentials akin to a username
+        and password used to authenticate with the Infisical API. With that, press on the key icon on the identity to generate a **Client Secret**
+        for it.
+        
+        ![identities client secret create](../../images/platform/identities/identities-org-client-secret.png)
+        ![identities client secret create](../../images/platform/identities/identities-org-client-secret-create-1.png)
+        ![identities client secret create](../../images/platform/identities/identities-org-client-secret-create-2.png)
+    </Step>
+    <Step title="Add the identity to the project">
+        To enable the identity to access your project, we need to add it to the project. To do this, head over to the **Demo App** Project Settings > Access Control > Machine Identities and press **Add identity**.

-Head to your Project Settings, where you created your service token, and un-check the **E2EE** setting.
+        Next, select the identity you want to add to the project and the role you want to assign it.

-## Retrieve Secret
+        ![identities project](../../images/platform/identities/identities-project.png)
+        
+        ![identities project create](../../images/platform/identities/identities-project-create.png)
+    </Step>
+    <Step title="Get an access token for the Infisical API">
+        To access the Infisical API as the identity, you should first perform a login operation
+        that is to exchange the **Client ID** and **Client Secret** of the identity for an access token
+        by making a request to the `/api/v1/auth/universal-auth/login` endpoint.
+        
+        #### Sample request

-Retrieve a secret from the project and environment in Infisical scoped to your service token by making a HTTP request with the following format/details:
+        ```
+        curl --location --request POST 'https://app.infisical.com/api/v1/auth/universal-auth/login' \
+        --header 'Content-Type: application/x-www-form-urlencoded' \
+        --data-urlencode 'clientSecret=<client_secret>' \
+        --data-urlencode 'clientId=<client_id>'
+        ```
+        
+        #### Sample response
+        
+        ```
+        {
+        "accessToken": "...",
+        "expiresIn": 7200,
+        "tokenType": "Bearer"
+        }
+        ```

-```bash
-curl --location --request GET 'https://app.infisical.com/api/v3/secrets/raw/secretName?workspaceId=workspaceId&environment=environment' \
-    --header 'Authorization: Bearer serviceToken'
-```
+        Next, we can use the access token to authenticate with the [Infisical API](/api-reference/overview/introduction) to read/write secrets
+        
+        <Note>
+        Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
+        the default TTL is `7200` seconds which can be adjusted.

-<ParamField path="secretName" type="string" required>
-    Name of secret to retrieve
-</ParamField>
-<ParamField query="workspaceId" type="string" required>
-    The ID of the workspace
-</ParamField>
-<ParamField query="environment" type="string" required>
-    The environment slug
-</ParamField>
-<ParamField query="secretPath" type="string" default="/" optional>
-    Path to secrets in workspace
-</ParamField>
-<ParamField query="type" type="string" optional default="personal">
-    The type of the secret. Valid options are “shared” or “personal”
-</ParamField>
+        If an identity access token expires, it can no longer authenticate with the Infisical API. In this case,
+        a new access token should be obtained from the aforementioned login operation.
+        </Note>
+    </Step>
+    <Step title="Fetch back secret">
+        Finally, you can fetch the secret `FOO=BAR` back from **Step 1** by including the access token in the previous step in another request to the `/api/v3/secrets/raw/{secretName}` endpoint.

-Depending on your application requirements, you may wish to use Infisical's API in different ways such as by retaining **E2EE**
-or fetching multiple secrets at once instead of one at a time.
+        ### Sample request
+        
+        ```
+        curl --location --request GET 'http://localhost:8080/api/v3/secrets/raw/FOO?workspaceId=657830d579cfc8415d06ce5b&environment=dev' \
+            --header 'Authorization: Bearer <access_token>'
+        ```
+        
+        ### Sample response

-Whatever the case, we recommend glossing over the [API Examples](/api-reference/overview/examples/note)
-to gain a deeper understanding of how you to best leverage the Infisical API for your use-case.
+        ```
+        {
+            "secret": {
+                "_id": "6564234b934d634e1fcd6cdf",
+                "version": 1,
+                "workspace": "6564173e934d634e1fcd6950",
+                "type": "shared",
+                "environment": "dev",
+                "secretKey": "FOO2",
+                "secretValue": "BAR2",
+                "secretComment": ""
+            }
+        }
+        ```
+        
+        Note that you can fetch a list of secrets back by making a request to the `/api/v3/secrets/raw` endpoint.
+    </Step>
+</Steps>

 See also:

- Explore the [API Examples](/api-reference/overview/examples/note)
 - [API Reference](/api-reference/overview/introduction)
--- a/docs/images/getting-started/api/org-create-project-1.png
+++ b/docs/images/getting-started/api/org-create-project-1.png
--- a/docs/images/getting-started/api/org-create-project-2.png
+++ b/docs/images/getting-started/api/org-create-project-2.png
--- a/docs/images/getting-started/api/project-create-secret.png
+++ b/docs/images/getting-started/api/project-create-secret.png
--- a/docs/images/getting-started/api/project-dashboard.png
+++ b/docs/images/getting-started/api/project-dashboard.png
--- a/docs/images/getting-started/api/project-explore-env.png
+++ b/docs/images/getting-started/api/project-explore-env.png