docs(stripe): clarify api_key_id vs api_key_name vault options (supabase#595)

* Initial plan

* Improve Stripe FDW docs: clarify api_key_id and api_key_name vault options usage

Agent-Logs-Url: https://github.com/supabase/wrappers/sessions/57afec13-50a3-4077-86e8-cc23196407f6

Co-authored-by: burmecia <[email protected]>

* Fix stripe docs: revert tab split, add descriptions inside existing With Vault tab

Agent-Logs-Url: https://github.com/supabase/wrappers/sessions/84fc15a3-8220-4d92-83a6-641528a1b1b3

Co-authored-by: burmecia <[email protected]>

* Update docs/catalog/stripe.md

Co-authored-by: Copilot <[email protected]>

* docs(stripe): show two separate create server examples for api_key_id vs api_key_name

Agent-Logs-Url: https://github.com/supabase/wrappers/sessions/bd13c673-32e0-4c55-9ffd-ff4e43c3832a

Co-authored-by: burmecia <[email protected]>

* docs(stripe): use consistent 'secret id' terminology and alias query result to key_id

Agent-Logs-Url: https://github.com/supabase/wrappers/sessions/84b96a3b-ebb1-46a0-9b6f-2255ba7bf03a

Co-authored-by: burmecia <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: burmecia <[email protected]>
Co-authored-by: Bo Lu <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

docs/catalog/stripe.md

@@ -40,27 +40,48 @@ create foreign data wrapper stripe_wrapper
 By default, Postgres stores FDW credentials inside `pg_catalog.pg_foreign_server` in plain text. Anyone with access to this table will be able to view these credentials. Wrappers is designed to work with [Vault](https://supabase.com/docs/guides/database/vault), which provides an additional level of security for storing credentials. We recommend using Vault to store your credentials.
 
 ```sql
--- Save your Stripe API key in Vault and retrieve the created `key_id`
+-- Save your Stripe API key in Vault and retrieve the secret id (UUID) used for api_key_id
 select vault.create_secret(
   '<Stripe API key>',
-  'stripe',
-  'Stripe API key for Wrappers'
+  'stripe',                          -- key name, used for api_key_name option
+  'Stripe API key for Wrappers'      -- key description
 );
 ```
 
+The `vault.create_secret` function returns the secret id (UUID) used for the `api_key_id` option. You can also retrieve this id later:
+
+```sql
+select id as key_id from vault.secrets where name = 'stripe';
+```
+
 ### Connecting to Stripe
 
 We need to provide Postgres with the credentials to connect to Stripe, and any additional options. We can do this using the `create server` command:
 
 
 === "With Vault"
 
+    You can connect using either `api_key_id` or `api_key_name` — only one is required. If both are provided, `api_key_id` takes precedence.
+
+    **Option 1: using `api_key_id`** (the UUID returned by `vault.create_secret`)
+
+    ```sql
+    create server stripe_server
+      foreign data wrapper stripe_wrapper
+      options (
+        api_key_id '<key_id>',  -- UUID returned by vault.create_secret, or retrieved via: select id from vault.secrets where name = 'stripe'
+        api_url 'https://api.stripe.com/v1/',  -- Stripe API base URL, optional. Default is 'https://api.stripe.com/v1/'
+        api_version '2024-06-20'  -- Stripe API version, optional. Default is your Stripe account’s default API version.
+      );
+    ```
+
+    **Option 2: using `api_key_name`** (the name given to the secret, i.e. the second argument to `vault.create_secret`)
+
     ```sql
     create server stripe_server
       foreign data wrapper stripe_wrapper
       options (
-        api_key_id '<key_ID>', -- The Key ID from above, required if api_key_name is not specified.
-        api_key_name '<key_Name>', -- The Key Name from above, required if api_key_id is not specified.
+        api_key_name 'stripe',  -- name used when creating the secret via vault.create_secret
         api_url 'https://api.stripe.com/v1/',  -- Stripe API base URL, optional. Default is 'https://api.stripe.com/v1/'
         api_version '2024-06-20'  -- Stripe API version, optional. Default is your Stripe account’s default API version.
       );