# How to use secrets in an SDK An SDK that needs a credential at runtime, such as an API key, declares a `secret` plug. After a user connects the plug to a secret slot, the SDK can request the value when it is needed without shipping or storing the value itself. Use this guide to add one of the supported delivery patterns to an existing SDK. ## Prerequisites Before starting, ensure you have these requirements satisfied: - An existing **SDKcraft** project. - A command, tool, or systemd service in the SDK that needs a credential at runtime. - A host keyring and the **secret-tool** utility to store a test value, as listed in [How to provide secrets to a workshop](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/provide-secrets.md#how-provide-secrets). ## Choose how the SDK receives the value Choose the delivery mechanism based on what consumes the credential: | What needs it | Mechanism | Why | |-------------------------------------------------|-------------------------------------------------------------|-----------------------------------------------------------------------------------------------| | A tool with a credential-helper setting | **workshopctl get-secret**,
called directly by the tool | The tool requests the value only when needed
without putting it in the tool’s environment | | A command that reads standard input | Pipe from **workshopctl get-secret** | The value can stay out of the command’s environment | | A command that requires an environment variable | An SDK-supplied wrapper | The variable exists only in the wrapper and the process it starts | | A long-running systemd service | `LoadCredential=` in the service unit | systemd requests the value on each start
and makes it available as a credential file | | A value the user passes for a single command | The user’s `--env` argument | The user supplies the value ad hoc,
without a slot or a connection | #### WARNING Never put a secret in SDK content, `sdkcraft.yaml`, workshop definitions, hooks, shell profiles, examples, or logs. Each of these is a file that ships, persists, or is shared, so a value written there outlives the moment it was needed. ## Declare a secret plug Add a `secret` plug to `sdkcraft.yaml`. The plug has a name and an interface, but no lookup attributes or value: ```yaml name: secret-demo # ... plugs: api-key: interface: secret ``` Only regular SDKs can declare secret plugs. Inside the workshop, the request identifier is `.`; for an SDK named `secret-demo` with the plug above, the identifier is `secret-demo.api-key`. **Workshop** never connects a secret plug automatically. Document the plug name and the credential it expects so users know which slot to create and connect. The SDK must also handle the plug being unconnected or the lookup failing. ## Connect the plug in a test workshop The plug has nothing to request until it’s connected to a secret slot. Slots don’t ship with the SDK: they belong to the `system` SDK, and each user adds one to their workshop definition, with lookup attributes that identify an item in their own keyring. To test the SDK, take the same steps with a throwaway value. Store the test value in the host keyring. **secret-tool** prompts for the value; enter the 23-byte `not-a-real-secret-value` to match the output of later steps: ```console $ secret-tool store --label="Secret demo test key" --collection=default service secret-demo account test ``` Build and install the SDK with **sdkcraft try**, as described in [Try the SDK](https://ubuntu.com/workshop/docs/how-to/develop-sdks/build-an-sdk.md#how-build-sdk-try): ```console $ sdkcraft try ``` In the test workshop definition, add a `secret` slot to the `system` SDK with attributes that match the stored item, and list the SDK with the `try-` prefix: ```yaml name: dev base: ubuntu@24.04 sdks: - name: system slots: demo-key: interface: secret attributes: service: secret-demo account: test - name: try-secret-demo ``` Launch the workshop: ```console $ workshop launch ``` Then connect the plug to the slot. The plug keeps the SDK’s own name, without the `try-` prefix: ```console $ workshop connect dev/secret-demo:api-key dev/system:demo-key ``` The connection persists when you rebuild the SDK and refresh the workshop in later steps. ## Request a secret on demand Run **workshopctl get-secret .** inside the workshop to request a connected secret: ```console $ workshopctl get-secret . ``` The command writes the value to standard output. Capture or pipe that output directly into the consuming tool; do not print it to a terminal or log. For example, the following check counts the bytes of the test value without displaying it: ```console $ workshop exec dev -- workshopctl get-secret secret-demo.api-key | wc -c 23 ``` When a request fails, **workshopctl** writes a short diagnostic to standard error and exits with a status that identifies the failure. To see one, disconnect the plug: ```console $ workshop disconnect dev/secret-demo:api-key ``` Then repeat the request; an unconnected plug returns status 3: ```console $ workshop exec dev -- workshopctl get-secret secret-demo.api-key secret plug "secret-demo.api-key" is not connected ``` Reconnect the plug before you continue: ```console $ workshop connect dev/secret-demo:api-key dev/system:demo-key ``` The [workshopctl get-secret reference](https://ubuntu.com/workshop/docs/reference/cli/workshopctl.md#ref-workshopctl-cli) lists every exit status. Branch on the status when the SDK needs to distinguish an unavailable provider, a missing item, multiple matches, or an unconnected plug. Every request also creates a `Retrieve secret` change. The change and its tasks record whether delivery succeeded and why it failed, but never contain the value. Use **workshop changes** and **workshop tasks** to troubleshoot an integration that hides the immediate error. ## Use a tool-native credential helper Prefer a tool-native credential helper when one is available. Configure the helper to run: ```console $ workshopctl get-secret . ``` The tool controls when it calls the helper and how long it retains the returned value. The value does not need to enter the tool’s environment. For example, Claude Code’s `apiKeyHelper` setting runs a command and uses its output as the API key. If the tool accepts the credential on standard input instead, pipe the command output directly into the tool. Keep shell tracing such as `set -x` disabled, because it can print assignments and command substitutions. ## Wrap a tool that requires an environment variable When a tool reads its credential only from an environment variable, ship a wrapper that requests the value and exports it only for the tool process. The following wrapper starts `bin/secret-demo-tool` with `SECRET_DEMO_API_KEY`. A value already supplied by the user takes precedence: ```shell #!/usr/bin/bash # Runs secret-demo-tool with the API key from the connected secret plug. # A key already set in the environment takes precedence. sdk_dir=$(dirname "$(dirname "$(readlink -f "$0")")") if [[ -z "${SECRET_DEMO_API_KEY:-}" ]]; then if key=$(workshopctl get-secret secret-demo.api-key); then export SECRET_DEMO_API_KEY="$key" fi unset key fi exec "$sdk_dir/bin/secret-demo-tool" "$@" ``` If the request fails, **workshopctl get-secret** already writes the diagnostic. The wrapper starts the tool without the variable, allowing the tool to use another login mechanism or report that the credential is missing. If a silent fallback is intentional, redirect standard error only for the request: ```shell if key=$(workshopctl get-secret secret-demo.api-key 2>/dev/null); then export SECRET_DEMO_API_KEY="$key" fi ``` The corresponding `Retrieve secret` change remains available for troubleshooting while **Workshop** retains it. Install the wrapper on `PATH` from the SDK’s `setup-base` hook: ```shell #!/usr/bin/bash cat >/etc/profile.d/secret-demo.sh <&2 exit 1 fi echo "secret-demo-service: started with a $(wc -c <"$key_file")-byte key" exec sleep infinity ``` Install the unit from `setup-base`. Runtime hooks receive `SDK_SYSTEMD_SECRET_SOCKET`, which is the socket systemd uses to request the value: ```shell #!/usr/bin/bash cat >/etc/profile.d/secret-demo.sh </etc/systemd/system/secret-demo.service <=` stays in the shell history, and other processes on the host can read it from the process list while the command runs. ## Review the exposure limits Each delivery mechanism keeps the value out of SDK content, but the value remains readable somewhere while it is in use: | Mechanism | What can read the value | What the SDK cannot clean up | |--------------------------------------|-----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | Tool-native helper or standard input | The process that consumes the command output
and anything to which that process passes it | While the plug is connected,
any process in the workshop can make a new request | | Command wrapper | The tool and every process it starts,
through the tool’s environment | While the plug is connected,
any process in the workshop can request the value
with **workshopctl get-secret** | | Systemd credential | The unit’s user, root,
and other processes running as that user | The credential file remains available
until systemd stops the service | | Single-command value | The command and every process it starts | A variable exported by the user’s shell
or by a tool such as direnv
stays available to every command run from that environment | Disconnecting a plug prevents new requests, but it cannot withdraw a value that a process has already received. Document this limitation for users, especially when the SDK can run autonomous tools. ## See also How-to guides: - [How to declare plugs and slots](https://ubuntu.com/workshop/docs/how-to/develop-sdks/declare-plugs-slots.md#how-declare-plugs-slots) - [How to provide secrets to a workshop](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/provide-secrets.md#how-provide-secrets) - [How to write runtime hooks](https://ubuntu.com/workshop/docs/how-to/develop-sdks/write-runtime-hooks.md#how-write-runtime-hooks) Reference: - [workshop changes](https://ubuntu.com/workshop/docs/reference/cli/workshop.md#ref-workshop-changes) - [workshop exec](https://ubuntu.com/workshop/docs/reference/cli/workshop.md#ref-workshop-exec) - [workshop run](https://ubuntu.com/workshop/docs/reference/cli/workshop.md#ref-workshop-run) - [workshop tasks](https://ubuntu.com/workshop/docs/reference/cli/workshop.md#ref-workshop-tasks) - [workshopctl (CLI)](https://ubuntu.com/workshop/docs/reference/cli/workshopctl.md#ref-workshopctl-cli)