> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sharing Secrets

> Share an API key with another company like 1Password — except they can use it without ever seeing the raw value, only toward approved domains, and you can stop sharing instantly.

# Sharing Secrets

Share a secret with an external party the way you'd share a password in 1Password — but with three things a password manager can't do:

* **They never see the value.** By default the recipient can *use* the secret (KnoxCall injects it into their API calls) but can never read the raw key.
* **It's locked to approved destinations.** The secret can only be sent to hosts you choose (e.g. `api.stripe.com`). It cannot be exfiltrated to a URL the recipient controls.
* **You can stop instantly.** Revoke a share and the recipient loses access on their very next request — no rotation, no waiting.

Because there is a **single canonical copy** of the secret (yours), any change you make — a rotation, a new value — is instantly live for everyone you've shared it with. Nothing to re-send.

***

## How it works

1. From a secret's **Sharing** tab, you invite someone by email and pick:
   * an **access level** (below),
   * the **destination domains** the secret may be used against,
   * which **environment**'s value to share.
2. The recipient gets an email with a claim link. They are **never** added to your workspace — instead they sign up for (or sign in to) their **own** KnoxCall workspace, where a **linked secret** appears.
3. In their workspace, the linked secret behaves like any other secret in their routes — but it holds no value of its own. At request time KnoxCall resolves it to your canonical value, injects it, and (if it's a `use only` share) never exposes it.

## Access levels

| Level                  | Can inject into routes |      Can reveal the value     |        Can edit the value       |
| ---------------------- | :--------------------: | :---------------------------: | :-----------------------------: |
| **Use only** (default) |            ✅           |               ❌               |                ❌                |
| **Can view**           |            ✅           | ✅ (with step-up verification) |                ❌                |
| **Can manage**         |            ✅           |               ✅               | ✅ (edits your canonical secret) |

`Use only` is the headline capability — grant the ability to *use* a credential without ever handing over the credential itself.

## Domain-locking

Domain-locking is **required by default**. When you share a secret you choose the destinations it may be injected toward:

* exact hostnames — `api.stripe.com`
* a single wildcard label — `*.example.com` (matches `a.example.com`, not the apex)

At request time, KnoxCall checks the resolved upstream host against this list **before sending anything**. If a recipient points a route at a host you didn't approve, the request is refused and the value is never transmitted. Choosing "any domain" is possible but is an explicit, audited opt-out — for a `use only` share it removes the only thing preventing the recipient from forwarding the value to themselves, so we don't recommend it.

## Revoking

Open the **Sharing** tab and choose **Stop sharing** on any recipient. Access ends immediately — the check happens on every request, uncached. Deleting a secret that is actively shared prompts you to revoke those shares first (or to revoke-and-delete in one step).

***

## What "never see the value" actually means (the honest version)

This is important to state plainly. Linked secret sharing is **recipient-opaque, platform-trusted, and destination-constrained** — it is **not** zero-knowledge:

* **Recipient-opaque:** the value is never revealed to the recipient through any product surface, and it never leaves KnoxCall toward a destination you didn't approve.
* **Platform-trusted:** KnoxCall's control plane decrypts your secret server-side to inject it (exactly as it does for your own routes today). The "never reveal" guarantee is an authorization + destination boundary, not a cryptographic one.
* **Your kill-switch:** if you use **customer-managed keys (BYOK)**, sealing your KMS revokes every share instantly and cryptographically — nothing can be injected.

In short: the recipient can *use* the credential against the destinations you allow, and can never see it or send it elsewhere — but they are trusting KnoxCall to hold the key, the same as you are.

<Note>
  Linked secrets work with the classic proxy (Routes). Sharing string, OAuth2, and certificate secrets is supported. Live and Test are isolated: a Live share never resolves a Test secret.
</Note>