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:
{
"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:
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:useOrbixEnvandBlockSecretsManagerstore values in browserlocalStorageunderorbix_env_secrets_<blockId>. - Never synced to collaborators: Values stored through
useOrbixEnvare never written intoblock.propsor 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 thatblockIdinorbixEgressFirewall. 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 ownmanifest.capabilities.network.domains. Cross-block scraping, undeclared domains, and tainted blocks are blocked. - Sealed Vault proxy (
sealBlockSecret/vaultProxyFetch): For deployments running the/api/vault-proxyedge function (configured withORBIX_VAULT_MASTER_SECRETand an active Supabase Auth session),@orbixdocs/sdkalso exportssealBlockSecretandvaultProxyFetch(and cross-origin HTML frames exposeOrbix.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-proxyis not deployed (such as offline or local-only dev), useuseOrbixEnvwithorbixFetchagainst explicitnetwork.domains.
Security guidelines for block authors
- Do not hardcode API keys, OAuth client secrets, or webhook tokens anywhere in your block source or
manifest.jsondefaults. - Do not store an API key in
useOrbixState,props.onChange, orprops.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 callingdeleteEnv(key)so users can revoke stored credentials on shared machines. - Do declare the exact target hostname in
manifest.capabilities.network.domainsrather than'*'so credentials can only be sent to the intended API origin.