Skip to Content
OrbixDocs
Block SDK · Guides

Use API keys safely

Declare per-block environment variables, read user-supplied keys with useOrbixEnv, and avoid leaking credentials into documents.

When a block connects to a third-party API (such as Linear, GitHub, or OpenAI), each user supplies their own API key locally rather than reading a hardcoded token from your source code.

Declaring env fields in manifest.json

List required keys under env in your manifest so users and Block Studio know what credentials your block expects:

manifest.json
{
  "id": "acme.linear-issues",
  "name": "Linear Issues",
  "version": "1.0.0",
  "sdk": "^3.0.0",
  "capabilities": {
    "network": {
      "domains": ["api.linear.app"],
      "methods": ["POST"]
    }
  },
  "env": {
    "LINEAR_API_KEY": {
      "label": "Linear Personal API Key",
      "description": "Used to query your assigned issues from api.linear.app.",
      "required": true,
      "secret": true,
      "placeholder": "lin_api_..."
    }
  }
}

Inside the Block Studio editor, you can enter or clear values for these keys from the top-right ••• menu under Environment Secrets.

Reading keys with useOrbixEnv

Call useOrbixEnv(props) inside your component to read, update, or clear environment values for the active block:

src/LinearBlock.tsx
import { useState } from 'react';
import {
  defineBlock,
  useBlockId,
  useOrbixEnv,
  orbixFetch,
  type BlockRenderProps,
} from '@orbixdocs/sdk';

export default defineBlock({
  manifest: {
    id: 'acme.linear-issues',
    name: 'Linear Issues',
    version: '1.0.0',
    sdk: '^3.0.0',
    capabilities: {
      network: {
        domains: ['api.linear.app'],
        methods: ['POST'],
      },
    },
    env: {
      LINEAR_API_KEY: {
        label: 'Linear API Key',
        required: true,
        secret: true,
      },
    },
  },
  component(props: BlockRenderProps) {
    const blockId = useBlockId();
    const { getEnv, setEnv, deleteEnv } = useOrbixEnv(props);
    const apiKey = getEnv('LINEAR_API_KEY');
    const [keyInput, setKeyInput] = useState('');
    const [viewerName, setViewerName] = useState<string | null>(null);

    if (!apiKey) {
      return (
        <div
          style={{
            padding: 16,
            borderRadius: 12,
            background: 'var(--orbix-card-bg, #16171b)',
            border: '1px solid var(--orbix-surface-border, #2a2b32)',
            color: 'var(--orbix-text-primary, #f4f4f5)',
          }}
        >
          <p style={{ marginTop: 0 }}>Enter your Linear API key (stored on this device only):</p>
          <input
            type="password"
            value={keyInput}
            onChange={(e) => setKeyInput(e.target.value)}
            placeholder="lin_api_..."
          />
          <button
            type="button"
            onClick={() => {
              if (keyInput.trim()) {
                setEnv('LINEAR_API_KEY', keyInput.trim());
                setKeyInput('');
              }
            }}
          >
            Save key
          </button>
        </div>
      );
    }

    const loadViewer = async () => {
      const res = await orbixFetch('https://api.linear.app/graphql', {
        method: 'POST',
        blockId,
        headers: {
          'Content-Type': 'application/json',
          Authorization: apiKey,
        },
        body: JSON.stringify({ query: '{ viewer { name } }' }),
      });
      const json = (await res.json()) as { data?: { viewer?: { name?: string } } };
      setViewerName(json.data?.viewer?.name ?? 'Connected');
    };

    return (
      <div>
        <div>Signed in: {viewerName ?? 'Ready'}</div>
        <button type="button" onClick={() => void loadViewer()}>
          Load profile
        </button>
        <button type="button" onClick={() => deleteEnv('LINEAR_API_KEY')}>
          Remove key
        </button>
      </div>
    );
  },
});

You can also render <EnvSetupCard envVar="LINEAR_API_KEY" label="Linear API Key" props={props} /> from @orbixdocs/sdk/ui (in both Block Studio and standalone npm builds) to display a masked key input whenever a required variable is unset.

Where secrets are stored and how DLP protects them

Understanding how BlockSecretsManager and orbixEgressFirewall handle stored values helps you design safe credential flows:

  • Device-local localStorage: useOrbixEnv and BlockSecretsManager store values in browser localStorage under orbix_env_secrets_<blockId>.
  • Never synced to collaborators: Values stored through useOrbixEnv are never written into block.props or synced to the document CRDT. Opening a shared document on another user's computer does not expose your API keys.
  • Per-block DLP fingerprinting: Whenever a secret string of 12 or more characters is saved through BlockSecretsManager, its fingerprint is bound to that blockId in orbixEgressFirewall. That block may include its own secret in HTTPS requests only when it has not read workspace/document data (untainted) and the target hostname is explicitly listed (no '*' wildcard) in its own manifest.capabilities.network.domains. Cross-block scraping, undeclared domains, and tainted blocks are blocked.
  • Sealed Vault proxy (sealBlockSecret / vaultProxyFetch): For deployments running the /api/vault-proxy edge function (configured with ORBIX_VAULT_MASTER_SECRET and an active Supabase Auth session), @orbixdocs/sdk also exports sealBlockSecret and vaultProxyFetch (and cross-origin HTML frames expose Orbix.vault.seal / Orbix.vault.fetch) to seal a secret into a 1-hour AES-256-GCM envelope pinned to { userId, blockId, allowedHost, allowedMethods } and inject credentials server-side. When /api/vault-proxy is not deployed (such as offline or local-only dev), use useOrbixEnv with orbixFetch against explicit network.domains.

Security guidelines for block authors

  • Do not hardcode API keys, OAuth client secrets, or webhook tokens anywhere in your block source or manifest.json defaults.
  • Do not store an API key in useOrbixState, props.onChange, or props.setProperty — doing so writes the plaintext key into the shared document where every collaborator and public link viewer can read it.
  • Do use <input type="password"> when prompting for a secret and provide a clear button calling deleteEnv(key) so users can revoke stored credentials on shared machines.
  • Do declare the exact target hostname in manifest.capabilities.network.domains rather than '*' so credentials can only be sent to the intended API origin.

On this page