Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
docs(secret-rotation): document Stripe API key rotation
Calvin7200ffa9e24b
diff --git a/docs/.vale/styles/config/vocabularies/Infisical/canonical/accept.txt b/docs/.vale/styles/config/vocabularies/Infisical/canonical/accept.txtindex 3253952bba..4008087e66 100644--- a/docs/.vale/styles/config/vocabularies/Infisical/canonical/accept.txt+++ b/docs/.vale/styles/config/vocabularies/Infisical/canonical/accept.txt@@ -628,3 +628,6 @@ MSBuild# --- Surfaced by the PAM Snowflake page ---DBeaversnowsql++# --- Surfaced by the Stripe API key rotation pages ---+Stripediff --git a/docs/api-reference/endpoints/secret-rotations/stripe-api-key/create.mdx b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/create.mdxnew file mode 100644index 0000000000..b25db1bbca--- /dev/null+++ b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/create.mdx@@ -0,0 +1,77 @@+---+title: "Create"+openapi: "POST /api/v2/secret-rotations/stripe-api-key"+---++<Note>+ Check out the configuration docs for [Stripe API Key Rotations](/documentation/platform/secret-rotation/stripe-api-key) to learn how to obtain the required parameters.+</Note>++Creates a Stripe API key secret rotation. Infisical will create and expire restricted API keys via your [Stripe connection](/integrations/app-connections/stripe) and write them to the specified secret path.++## Request body++| Field | Type | Required | Description |+|-------|------|----------|-------------|+| `name` | string | Yes | A unique name for the rotation (max 100 characters). |+| `projectId` | string (UUID) | Yes | The project ID. |+| `connectionId` | string (UUID) | Yes | ID of the Stripe app connection. |+| `environment` | string | Yes | Environment slug (e.g. `dev`, `prod`). |+| `secretPath` | string | Yes | Path where the generated API key secret will be stored. |+| `isAutoRotationEnabled` | boolean | No | Whether to rotate automatically on the schedule. Defaults to `true`. |+| `rotationInterval` | number | Yes | Days between rotations (minimum `1`). |+| `rotateAtUtc` | object | No | Time of day (UTC) to run rotation: `{ "hours", "minutes" }`. Defaults to `{ "hours": 0, "minutes": 0 }`. |+| `parameters.permissions` | string[] | Yes | The permissions granted to the generated restricted key. At least one is required. Stripe has no wildcard for full access, so granting every permission means listing all of them. |+| `parameters.connectPermissions` | string[] | No | The permissions the generated key holds when acting on behalf of a connected account. Only relevant if your Stripe account is a Connect platform. |+| `secretsMapping.apiKey` | string | Yes | Secret key name to store the generated restricted key's value (e.g. `STRIPE_API_KEY`). |+| `description` | string | No | Optional description. |++## Sample request++```bash+curl --request POST \+ --url https://us.infisical.com/api/v2/secret-rotations/stripe-api-key \+ --header 'Content-Type: application/json' \+ --header 'Authorization: Bearer <ACCESS_TOKEN>' \+ --data '{+ "name": "my-stripe-rotation",+ "projectId": "<project-id>",+ "description": "Stripe API key rotation",+ "connectionId": "<stripe-connection-id>",+ "environment": "dev",+ "secretPath": "/",+ "isAutoRotationEnabled": true,+ "rotationInterval": 30,+ "rotateAtUtc": { "hours": 0, "minutes": 0 },+ "parameters": {+ "permissions": ["charge_read", "charge_write", "customer_read", "customer_write"]+ },+ "secretsMapping": {+ "apiKey": "STRIPE_API_KEY"+ }+ }'+```++## Sample response++```json+{+ "secretRotation": {+ "id": "<rotation-id>",+ "name": "my-stripe-rotation",+ "description": "Stripe API key rotation",+ "secretsMapping": {+ "apiKey": "STRIPE_API_KEY"+ },+ "isAutoRotationEnabled": true,+ "activeIndex": 0,+ "connectionId": "<stripe-connection-id>",+ "rotationInterval": 30,+ "rotateAtUtc": { "hours": 0, "minutes": 0 },+ "type": "stripe-api-key",+ "parameters": {+ "permissions": ["charge_read", "charge_write", "customer_read", "customer_write"]+ }+ }+}+```diff --git a/docs/api-reference/endpoints/secret-rotations/stripe-api-key/delete.mdx b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/delete.mdxnew file mode 100644index 0000000000..9fc7a2fa53--- /dev/null+++ b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/delete.mdx@@ -0,0 +1,4 @@+---+title: "Delete"+openapi: "DELETE /api/v2/secret-rotations/stripe-api-key/{rotationId}"+---diff --git a/docs/api-reference/endpoints/secret-rotations/stripe-api-key/get-by-id.mdx b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/get-by-id.mdxnew file mode 100644index 0000000000..4d089170af--- /dev/null+++ b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/get-by-id.mdx@@ -0,0 +1,4 @@+---+title: "Get by ID"+openapi: "GET /api/v2/secret-rotations/stripe-api-key/{rotationId}"+---diff --git a/docs/api-reference/endpoints/secret-rotations/stripe-api-key/get-by-name.mdx b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/get-by-name.mdxnew file mode 100644index 0000000000..69a1d69e0f--- /dev/null+++ b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/get-by-name.mdx@@ -0,0 +1,4 @@+---+title: "Get by name"+openapi: "GET /api/v2/secret-rotations/stripe-api-key/rotation-name/{rotationName}"+---diff --git a/docs/api-reference/endpoints/secret-rotations/stripe-api-key/get-generated-credentials-by-id.mdx b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/get-generated-credentials-by-id.mdxnew file mode 100644index 0000000000..fec338b65f--- /dev/null+++ b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/get-generated-credentials-by-id.mdx@@ -0,0 +1,4 @@+---+title: "Get credentials by ID"+openapi: "GET /api/v2/secret-rotations/stripe-api-key/{rotationId}/generated-credentials"+---diff --git a/docs/api-reference/endpoints/secret-rotations/stripe-api-key/list.mdx b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/list.mdxnew file mode 100644index 0000000000..948910da4d--- /dev/null+++ b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/list.mdx@@ -0,0 +1,4 @@+---+title: "List"+openapi: "GET /api/v2/secret-rotations/stripe-api-key"+---diff --git a/docs/api-reference/endpoints/secret-rotations/stripe-api-key/rotate-secrets.mdx b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/rotate-secrets.mdxnew file mode 100644index 0000000000..e8e5ff9728--- /dev/null+++ b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/rotate-secrets.mdx@@ -0,0 +1,4 @@+---+title: "Rotate secrets"+openapi: "POST /api/v2/secret-rotations/stripe-api-key/{rotationId}/rotate-secrets"+---diff --git a/docs/api-reference/endpoints/secret-rotations/stripe-api-key/update.mdx b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/update.mdxnew file mode 100644index 0000000000..68d431a093--- /dev/null+++ b/docs/api-reference/endpoints/secret-rotations/stripe-api-key/update.mdx@@ -0,0 +1,4 @@+---+title: "Update"+openapi: "PATCH /api/v2/secret-rotations/stripe-api-key/{rotationId}"+---diff --git a/docs/docs.json b/docs/docs.jsonindex b260bd5af5..e0e9630b12 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -328,6 +328,7 @@"documentation/platform/secret-rotation/openai-service-account","documentation/platform/secret-rotation/openrouter-api-key","documentation/platform/secret-rotation/salesforce-oauth-credentials",+ "documentation/platform/secret-rotation/stripe-api-key","documentation/platform/secret-rotation/supabase-api-key"]},@@ -1083,6 +1084,7 @@"integrations/app-connections/servicenow","integrations/app-connections/snowflake","integrations/app-connections/spacelift",+ "integrations/app-connections/stripe","integrations/app-connections/supabase","integrations/app-connections/teamcity","integrations/app-connections/terraform-cloud",@@ -3069,6 +3071,19 @@"api-reference/endpoints/secret-rotations/supabase-api-key/update"]},+ {+ "group": "Stripe API key",+ "pages": [+ "api-reference/endpoints/secret-rotations/stripe-api-key/create",+ "api-reference/endpoints/secret-rotations/stripe-api-key/delete",+ "api-reference/endpoints/secret-rotations/stripe-api-key/get-by-id",+ "api-reference/endpoints/secret-rotations/stripe-api-key/get-by-name",+ "api-reference/endpoints/secret-rotations/stripe-api-key/get-generated-credentials-by-id",+ "api-reference/endpoints/secret-rotations/stripe-api-key/list",+ "api-reference/endpoints/secret-rotations/stripe-api-key/rotate-secrets",+ "api-reference/endpoints/secret-rotations/stripe-api-key/update"+ ]+ },{"group": "HP iLO local account","pages": [diff --git a/docs/documentation/platform/secret-rotation/stripe-api-key.mdx b/docs/documentation/platform/secret-rotation/stripe-api-key.mdxnew file mode 100644index 0000000000..bc4016ed4f--- /dev/null+++ b/docs/documentation/platform/secret-rotation/stripe-api-key.mdx@@ -0,0 +1,118 @@+---+title: "Stripe API key"+description: "Learn how to automatically rotate Stripe restricted API keys."+---++<Note>+ **Rotation Type: Dual-Phase**++ This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.+</Note>++Stripe API key rotation mints a new [restricted key](https://docs.stripe.com/keys#limit-access-with-restricted-api-keys) on the interval you set, so your applications always have a working credential without a manual key swap. A few things about how it behaves are worth knowing before you set it up.++- **The minted key's mode follows your Stripe account's own key.** If your Stripe account is in test mode, every key this rotation generates is a test-mode key. Your account decides the mode; the rotation doesn't, and there's no setting to override it.+- **The generated value is a restricted key (`rk_...`), never a secret key (`sk_...`).** If anything downstream checks the credential's prefix, check it against `rk_`.+- **Infisical never touches the key you already have.** Rotation only creates and retires the keys it generates itself. Your original Stripe key keeps working until you manually delete it in the Stripe dashboard, once you've confirmed your applications are reading the rotated secret.+- **Retiring a key doesn't kill it instantly.** When a key is due for retirement, Infisical expires it through Stripe, but Stripe decides when that expiration takes effect. A retired key can keep authenticating requests for a short window afterward, so don't build anything that assumes the old key stops working the moment rotation runs.++## Prerequisites++- Create a [Stripe Connection](/integrations/app-connections/stripe). That connection is used to create and expire restricted API keys on your behalf during rotation.+- Your Stripe account must have access to the [Managed API Keys API](/integrations/app-connections/stripe), which Stripe currently offers as a private preview.++## Create a Stripe API key rotation in Infisical++<Tabs>+ <Tab title="Infisical UI">+ 1. Navigate to your Secrets Manager Project's Dashboard and select **Add Secret Rotation** from the actions dropdown.++ ++ 2. Select the **Stripe API Key** option.++ 3. Configure the rotation behavior, then select **Next**.++ - **Stripe Connection** - The connection that will create and expire restricted API keys during rotation.+ - **Rotation Interval** - The interval, in days, after which a rotation is triggered.+ - **Rotate At** - The local time of day when rotation runs once the interval has elapsed.+ - **Auto-Rotation Enabled** - Whether to rotate automatically on the interval. Turn off to rotate only manually or pause rotation.++ 4. Set the Stripe API key parameters, then select **Next**.++ - **Permissions** - The permissions granted to the generated key. Stripe's Managed API Keys API has no wildcard for "all access", so a key with full access is one where every permission in the list is selected individually. If you already have a Stripe API key with the permissions you want, you can copy its permissions instead of selecting them by hand.+ - **Connect permissions** (optional) - Permissions the generated key holds when acting on behalf of a connected account. This only matters if your Stripe account is a [Connect](https://docs.stripe.com/connect) platform; leave it empty otherwise.++ 5. Specify the secret name that the rotated API key will be mapped to. Then select **Next**.++ - **API Key** - The name of the secret in Infisical where the generated restricted key's value will be stored.++ 6. Give your rotation a name and description (optional). Then select **Next**.++ - **Name** - A slug-friendly name for this rotation configuration.+ - **Description** (optional) - Notes about this rotation.++ 7. Review your configuration, then select **Create Secret Rotation**.++ 8. Your **Stripe API Key** rotation is created. The current restricted key is available as a secret at the mapped path. Rotations will create a new key, switch the active secret to it, then expire the previous key for zero-downtime rotation.++ <Note>+ Infisical only ever expires the keys it created. Your account's existing keys, including any key you were using before you set up this rotation, are left alone.+ </Note>+ </Tab>+ <Tab title="API">+ To create a Stripe API Key rotation, call the [Create Stripe API Key Rotation](/api-reference/endpoints/secret-rotations/stripe-api-key/create) API endpoint.++ ### Sample request++ ```bash Request+ curl --request POST \+ --url https://us.infisical.com/api/v2/secret-rotations/stripe-api-key \+ --header 'Content-Type: application/json' \+ --data '{+ "name": "my-stripe-rotation",+ "projectId": "<project-id>",+ "description": "Stripe API key rotation",+ "connectionId": "<stripe-connection-id>",+ "environment": "dev",+ "secretPath": "/",+ "isAutoRotationEnabled": true,+ "rotationInterval": 30,+ "rotateAtUtc": {+ "hours": 0,+ "minutes": 0+ },+ "parameters": {+ "permissions": ["charge_read", "charge_write", "customer_read", "customer_write"]+ },+ "secretsMapping": {+ "apiKey": "STRIPE_API_KEY"+ }+ }'+ ```++ ### Sample response++ ```bash Response+ {+ "secretRotation": {+ "id": "<rotation-id>",+ "name": "my-stripe-rotation",+ "description": "Stripe API key rotation",+ "secretsMapping": {+ "apiKey": "STRIPE_API_KEY"+ },+ "isAutoRotationEnabled": true,+ "activeIndex": 0,+ "connectionId": "<stripe-connection-id>",+ "rotationInterval": 30,+ "rotateAtUtc": { "hours": 0, "minutes": 0 },+ "type": "stripe-api-key",+ "parameters": {+ "permissions": ["charge_read", "charge_write", "customer_read", "customer_write"]+ }+ }+ }+ ```+ </Tab>+</Tabs>diff --git a/docs/integrations/app-connections/stripe.mdx b/docs/integrations/app-connections/stripe.mdxnew file mode 100644index 0000000000..774b989135--- /dev/null+++ b/docs/integrations/app-connections/stripe.mdx@@ -0,0 +1,76 @@+---+title: "Stripe connection"+sidebarTitle: "Stripe"+description: "Learn how to configure a Stripe Connection for Infisical."+---++Infisical supports connecting to Stripe through an installed Stripe App, so it can create and expire restricted API keys on your behalf for [Stripe API key rotation](/documentation/platform/secret-rotation/stripe-api-key).++<Warning>+ This connection depends on two things only Stripe can grant, so confirm both before you invest time setting it up:++ - The Stripe App used for the connection must hold the `api_key_write` permission, which Stripe grants only after reviewing the app.+ - Your Stripe account needs access to Stripe's [Managed API Keys API](https://docs.stripe.com/api-keys), which Stripe currently offers as a private preview.++ Without both, installing the app succeeds but rotation can't create keys. If you're on Infisical Cloud, both are already in place. If you're self-hosting, see the setup section below before you start.+</Warning>++<Accordion title="Self-hosted instance setup">+ A self-hosted instance needs its own Stripe App, since the `api_key_write` permission and Managed API Keys access are both granted to a specific app rather than shared across every Infisical deployment.++ **Prerequisites:**+ - A Stripe account you control, to own the app+ - Self-hosted Infisical instance with a public HTTPS domain++ <Steps>+ <Step title="Request Stripe App approval">+ Register a Stripe App and request the `api_key_write` permission for it. Stripe reviews this manually, so expect it to take longer than a typical API key request.++ In the same request (or a follow-up to Stripe support), ask Stripe to enable your account for the Managed API Keys API. It's in private preview, so Stripe has to turn it on for you rather than you turning it on yourself.+ </Step>+ <Step title="Set the app's redirect URI">+ Configure your app's OAuth redirect URI as `https://your-domain.com/organization/app-connections/stripe/oauth/callback`, using your instance's own domain.++ <Note>+ Stripe requires HTTPS on this URI, with no exception for local development. The URI also has to match what your browser sends exactly, so it must agree with your instance's `SITE_URL` or Stripe rejects the install before you see a consent screen.+ </Note>+ </Step>+ <Step title="Add your Stripe App credentials to Infisical">+ From the Stripe dashboard, collect your app's **Client ID** and its **OAuth install link**, and the **secret key** of the Stripe account that owns the app.++ Set the following environment variables on your Infisical instance:++ - `INF_APP_CONNECTION_STRIPE_OAUTH_CLIENT_ID`: The Client ID of your Stripe App.+ - `INF_APP_CONNECTION_STRIPE_OAUTH_AUTHORIZE_URL`: The OAuth install link for your Stripe App, copied from the Stripe dashboard. Stripe issues a different link per mode, and it must match the mode of the secret key below.+ - `INF_APP_CONNECTION_STRIPE_SECRET_KEY`: The secret key of the Stripe account that owns your Stripe App. Infisical authenticates as this account when it manages keys on a connected account's behalf.++ Restart your instance once these are set.+ </Step>+ </Steps>+</Accordion>++## Setup Stripe connection in Infisical++<Steps>+ <Step title="Navigate to App Connections">+ Navigate to the **Integrations** tab in the desired project, then select **App Connections**.++ + </Step>+ <Step title="Add Connection">+ Select the **Stripe Connection** option from the connection options modal.+ </Step>+ <Step title="Connect to Stripe">+ Select **Connect to Stripe**. You'll be redirected to Stripe to install the Infisical app and choose the account Infisical should manage API keys for.+ </Step>+ <Step title="Install and authorize">+ Review the permissions and install the app on the Stripe account you want to connect. Stripe redirects you back to Infisical once you approve it.+ </Step>+ <Step title="Connection created">+ Your **Stripe Connection** is now available for use in your Infisical projects.+ </Step>+</Steps>++<Info>+ Uninstalling the app from the Stripe side, or having Stripe revoke it, breaks the connection. Reconnect from Infisical to restore it.+</Info>diff --git a/docs/self-hosting/configuration/envars.mdx b/docs/self-hosting/configuration/envars.mdxindex f4fc56c9e3..41d71f46ac 100644--- a/docs/self-hosting/configuration/envars.mdx+++ b/docs/self-hosting/configuration/envars.mdx@@ -131,7 +131,7 @@ Example values:Defaults to `false` so an operator-configured forward proxy keeps working.<Note>- Enable this only if your instance does **not** rely on an outbound+ Enable this only if your instance **doesn't** rely on an outbound`HTTP_PROXY` / `HTTPS_PROXY` for egress. When a proxy is in use, the IP pincan't extend past the proxy (the proxy resolves the target itself), soleaving this off is the correct choice for proxied deployments.@@ -283,7 +283,7 @@ and raising it is the right move.<Tip>Prefer scaling reads with `DB_READ_REPLICAS` over enlarging the primary pool. A connection pooler such asPgBouncer or RDS Proxy is only worth the extra hop and failure domain once instance count alone pushes you- near `max_connections`, and note that a pooler in transaction mode does **not** reclaim connections held+ near `max_connections`, and note that a pooler in transaction mode **doesn't** reclaim connections heldopen inside a transaction.</Tip>diff --git a/docs/snippets/RotationsBrowser.jsx b/docs/snippets/RotationsBrowser.jsxindex d6739fcce8..caf65e3811 100644--- a/docs/snippets/RotationsBrowser.jsx+++ b/docs/snippets/RotationsBrowser.jsx@@ -239,6 +239,15 @@ export const RotationsBrowser = () => {category: "AI & LLM",rotationType: "Dual-Phase",},+ {+ name: "Stripe API Key",+ slug: "stripe-api-key",+ path: "/documentation/platform/secret-rotation/stripe-api-key",+ description:+ "Learn how to automatically rotate Stripe restricted API keys.",+ category: "SaaS",+ rotationType: "Dual-Phase",+ },{name: "Snowflake User Key Pair",slug: "snowflake-user-key-pair",