Merge pull request #149 from phasehq/feat--add-cross-app-secret-ref-syntax

feat: add cross app secret ref syntax

Author: nimish-ks

src/pages/cli/commands.mdx

@@ -719,7 +719,7 @@ This command checks for updates and installs the latest version of the Phase CLI
 
 ---
 
-## Secret referencing
+## 🔗 Secret referencing
 
 You can set a value of a secret to a value of another by simply pointing to it via the following syntax.
 
@@ -731,6 +731,7 @@ You can set a value of a secret to a value of another by simply pointing to it v
 | `${staging.DEBUG}` | `staging` | `/` (root of staging environment) | DEBUG | Cross-environment reference to a secret at the root (/). |
 | `${production./frontend/SECRET_KEY}` | `production` | `/frontend/` | SECRET_KEY | Cross-environment reference to a secret in a specific path. |
 | `${/backend/payments/STRIPE_KEY}` | same environment | `/backend/payments/` | STRIPE_KEY | Local reference with a specified path within the same environment. |
+| `${backend_api::production./frontend/SECRET_KEY}` | `production` (in `backend_api` app) | `/frontend/` | SECRET_KEY | Cross-application reference to a secret in a specific path within another application. |
 
 For more information see: [Phase Console Secrets](/console/secrets)
 

src/pages/console/secrets.mdx

@@ -58,6 +58,17 @@ DATABASE_URL=postgresql://j_mclaren:6c37810ec6e74ec3228416d2844564fceb99ebd94b29
 | `${staging.DEBUG}` | `staging` | `/` (root of staging environment) | DEBUG | Cross-environment reference to a secret at the root (/). |
 | `${production./frontend/SECRET_KEY}` | `production` | `/frontend/` | SECRET_KEY | Cross-environment reference to a secret in a specific path. |
 | `${/backend/payments/STRIPE_KEY}` | same environment | `/backend/payments/` | STRIPE_KEY | Local reference with a specified path within the same environment. |
+| `${backend_api::production./frontend/SECRET_KEY}` | `production` (in `backend_api` app) | `/frontend/` | SECRET_KEY | Cross-application reference to a secret in a specific path within another application. |
+
+#### Please note the following when using secret referencing:
+
+- **Authentication requirements**: Your authentication token must have access to all referenced secrets across apps, environments, and paths. If access is insufficient, the reference won't be resolved and will be returned with the original syntax. For example, if you have access to the `production` environment in `backend_api` but not in `frontend`, the value `${backend_api::production./frontend/SECRET_KEY}` will remain unresolved.
+
+- **Third-party sync integration behavior**: When syncing to third-party services, Phase requires all secret references to be resolvable. The sync will fail if any referenced secret doesn't exist in its specified location (locally, in a path, or in an app). This design ensures third-party platforms never receive broken references, as many support their own native referencing syntax.
+
+- **Name collision handling**: If two or more applications in your organization share the same name (case insensitive), any secret reference to these applications will be deemed ambiguous and will be returned unresolved when accessed via the REST API. Additionally, any sync operation involving these ambiguous references will fail with an error message.
+
+- **Server-side Encryption (SSE)**: For references to resolve over the Public API or native integrations, all referenced apps must have SSE enabled. If a secret is being referenced in an app without SSE, the reference will not resolve and will be returned as-is over the API, and sync jobs will fail.  Note: SSE is not required for references to resolve when using E2E enabled clients such as the CLI or SDKs.
 
 ## Override a Secret (Personal Secrets)