Secrets, Auth, and Runtime Paths

This page collects a few authoring rules that are easy to miss when building task Blocks and reusable Flows: how to declare third-party secrets, how to access OOMOL authentication, when to prefer Fusion, and how to handle user-facing path inputs safely.

Third-Party Secrets

If a task needs a third-party API key, model it as a secret Handle rather than a plain string.

inputs_def:
  - handle: api_key
    json_schema:
      contentMediaType: oomol/secret
      type: string
    value: ${{OO_SECRET:Third Part,Third Part,Third Part_API_KEY}}

Why this matters:

• It prevents users from treating credentials like ordinary text parameters.
• It integrates with OOMOL Studio secret management.
• It avoids exposing sensitive information in ordinary inputs.

For general secret usage in the UI, see Universal Block Settings.

OOMOL Auth Is Different from Third-Party Secrets

OOMOL platform authentication should not be declared as a YAML secret Handle.

Instead, access the OOMOL token from runtime context:

• Python: await context.oomol_token()
• TypeScript: await context.getOomolToken()

Use these runtime APIs when the task needs to call OOMOL-owned services.

Prefer Fusion When It Covers the Capability

Before asking users to configure a third-party API key, check whether OOMOL Fusion already provides the capability you need.

Prefer Fusion when:

• The required model or capability is already available through OOMOL services.
• You want to reduce setup friction for users.
• You want authentication to follow the OOMOL token flow instead of external secret management.

Prefer a third-party secret only when Fusion does not cover the requirement or when the task truly depends on a user-owned external account.

For concrete usage examples, see Fusion SDK Overview, Fusion SDK for TypeScript, and Fusion SDK for Python.

User-Facing Path Handles

Path Handles are often user-facing, especially for output folders, save locations, or optional working directories.

The safest default pattern is:

1. Mark the path Handle as optional when it is genuinely optional.
2. Avoid fake placeholder paths.
3. Fall back in runtime code to the current session directory when the user leaves it empty.

Example YAML:

inputs_def:
  - handle: output_dir
    json_schema:
      type: string
      ui:widget: dir
    nullable: true

Runtime Path Fallback

If an optional path is left empty, resolve it in code using the session directory for the current run.

TypeScript example:

export default async function main(inputs: { output_dir?: string | null }, context: { sessionDir: string }) {
  const outputDir = inputs.output_dir || context.sessionDir;
  return { output_dir: outputDir };
}

Python example:

async def main(inputs, context):
    output_dir = inputs.get("output_dir") or context.session_dir
    return {"output_dir": output_dir}

This pattern keeps the YAML contract simple while still giving advanced users a way to override the destination explicitly.

Recommended Decision Rules

Use these shortcuts when authoring:

• If the value is a user-owned external credential, use contentMediaType: oomol/secret.
• If the value is OOMOL platform auth, get it from runtime context instead of YAML.
• If the capability is already available through Fusion, prefer Fusion before introducing a new external secret.
• If a path input is optional, model it as optional and fall back to context.sessionDir or context.session_dir.

Common Mistakes

Mistake	Better approach
Asking for an external model key when OOMOL Fusion already covers the use case	Use Fusion and OOMOL auth
Declaring OOMOL auth as a YAML secret	Read the token from runtime context
Using a plain string Handle for a third-party API key	Use contentMediaType: oomol/secret
Forcing users to enter an output path every run	Make it optional and fall back to the session directory
Using a fake default directory just to satisfy validation	Keep the Handle optional and resolve the path in code

For YAML structure details, see Flow YAML Authoring.