diff --git a/docs/api-reference/overview/authentication.mdx b/docs/api-reference/overview/authentication.mdx index 2f1e8a721..dc516a9ee 100644 --- 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. - + 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) - + 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) - + 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) - + 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. diff --git a/docs/documentation/getting-started/api.mdx b/docs/documentation/getting-started/api.mdx index 279982911..48a6f2ee0 100644 --- 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. + + + 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. + + For this brief, you'll need to disable end-to-end encryption in your Project Settings + + + + 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**. - - 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). - + ![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 + + + 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) + + + 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) + + + 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=' \ + --data-urlencode 'clientId=' + ``` + + #### 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 + + + 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. - - Name of secret to retrieve - - - The ID of the workspace - - - The environment slug - - - Path to secrets in workspace - - - The type of the secret. Valid options are “shared” or “personal” - + 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. + + + + 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 ' + ``` + + ### 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. + + See also: -- Explore the [API Examples](/api-reference/overview/examples/note) - [API Reference](/api-reference/overview/introduction) \ No newline at end of file diff --git a/docs/images/getting-started/api/org-create-project-1.png b/docs/images/getting-started/api/org-create-project-1.png new file mode 100644 index 000000000..468a264f0 Binary files /dev/null and b/docs/images/getting-started/api/org-create-project-1.png differ diff --git a/docs/images/getting-started/api/org-create-project-2.png b/docs/images/getting-started/api/org-create-project-2.png new file mode 100644 index 000000000..ecf420f66 Binary files /dev/null and b/docs/images/getting-started/api/org-create-project-2.png differ diff --git a/docs/images/getting-started/api/project-create-secret.png b/docs/images/getting-started/api/project-create-secret.png new file mode 100644 index 000000000..6fbe8af62 Binary files /dev/null and b/docs/images/getting-started/api/project-create-secret.png differ diff --git a/docs/images/getting-started/api/project-dashboard.png b/docs/images/getting-started/api/project-dashboard.png new file mode 100644 index 000000000..bf810d807 Binary files /dev/null and b/docs/images/getting-started/api/project-dashboard.png differ diff --git a/docs/images/getting-started/api/project-explore-env.png b/docs/images/getting-started/api/project-explore-env.png new file mode 100644 index 000000000..88a8f105f Binary files /dev/null and b/docs/images/getting-started/api/project-explore-env.png differ