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

# REST API

Infisical's REST API is the most flexible way to read/write secrets for your application.

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.

<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](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/images/getting-started/api/org-create-project-1.png)

    ![create project](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/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](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/images/getting-started/api/project-explore-env.png)

    ![create secret](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/images/getting-started/api/project-create-secret.png)

    ![project dashboard](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/images/getting-started/api/project-dashboard.png)

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

    ![identities organization](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/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](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/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](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/images/platform/identities/identities-org-create-auth-method.png)
  </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](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/images/platform/identities/identities-org-client-secret.png)
    ![identities client secret create](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/images/platform/identities/identities-org-client-secret-create-1.png)
    ![identities client secret create](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/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**.

    Next, select the identity you want to add to the project and the role you want to assign it.

    ![identities project](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/images/platform/identities/identities-project.png)

    ![identities project create](https://mintlify.s3-us-west-1.amazonaws.com/infisical-daniel-secret-tags-docs/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

    ```
    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"
    }
    ```

    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.

      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.

    ### 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

    ```
    {
        "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:

* [API Reference](/api-reference/overview/introduction)