matlab-secure-credentials

# Secure Credentials in MATLAB

Handle API keys, tokens, passwords, and passphrases with the **MATLAB Vault**, an
encrypted store built into MATLAB, instead of hardcoding them. This skill covers
*the credential* — storing it, retrieving it, and passing it into a connection to
any authenticated service.

## When to Use

- Connecting to any authenticated service or connection from MATLAB — a REST API,
  database, cloud storage, SFTP/FTP server, message queue, or any other.
- Any code that handles an API key, bearer token, password, or SSH key passphrase.
- Writing CI / batch / scheduled MATLAB that needs credentials with no user present.
- Refactoring credential-handling code, or persisting a config that includes a secret.
- A request to "keep credentials out of code," "don't commit secrets," or "do this
  the secure way."

## When NOT to Use

- Writing the connection/query/transfer logic itself when no credential is involved
  (e.g. a public API, a local file), or cleaning/transforming/aggregating data once it is
  in a table or timetable — use the relevant data-import skill (e.g. `matlab-analyze-data`,
  `matlab-use-database`).
- Integrating a third-party secret manager (HashiCorp Vault, AWS Secrets Manager,
  Azure Key Vault) — out of scope.
- OS-level or non-MATLAB key management.

## Decision Guide: Which Mechanism

Pick the mechanism by how the credential is supplied, not by habit.

| Situation | Use | Not |
|-----------|-----|-----|
| Credential is stored and reused across sessions | `setSecret` once, then `getSecret` at use | Hardcoding; a hand-rolled config file |
| You need to load a set of credentials at once (interactive setup, or non-interactive / CI / headless / scheduled) | `importSecrets` to populate the vault from a secrets file, then `getSecret`; or, in CI, `getenv` for a runner-injected value | `setSecret` in a headless job — it is only supported interactively |
| A function accepts credentials from a caller | `secretID` (a reference to the secret, not its value) | Storing the value in a struct field or argument |
| Credential is genuinely a process environment variable — a CI-injected secret, or a cloud SDK convention like `AWS_ACCESS_KEY_ID` | `getenv` — this is correct | Duplicating it into the vault for no reason |

The rule is **don't hardcode secrets** — not "never use environment variables." `getenv` is
the right tool when the secret is already a process env var; the vault is the right default
for credentials *you* store.

## Workflow

1. **Decide the mechanism** using the Decision Guide above.
2. **Store or populate** the credential:
   - Single secret, interactively: `setSecret("MyApiToken")` (MATLAB prompts for the value —
     never pass it as an argument; it takes only the name).
   - A set of secrets at once: `importSecrets("secrets.env")` loads names+values into the
     vault with no prompt — handy both for interactive setup and for non-interactive/CI.
3. **Retrieve at point of use** with `getSecret("MyApiToken")`, or hand a
   `secretID("MyApiToken")` to APIs that accept one (they resolve it at call time, so the
   value never lives in a variable).
4. **Wire it into the connection** — see Patterns below.
5. **Verify** with `isSecret("MyApiToken")` before reading or removing, and confirm no
   secret value appears in the script, logs, or any saved file.

## Key Functions

| Function | Purpose | Available From |
|----------|---------|----------------|
| `setSecret` | Add a secret to the vault; **interactive** — prompts for the value, takes only the name (`Overwrite=true` to update) | R2024a |
| `getSecret` | Retrieve a secret value (returns a string scalar) | R2024a |
| `isSecret` | Check whether a named secret exists | R2024a |
| `listSecrets` | List the names of stored secrets | R2024a |
| `removeSecret` | Delete a secret from the vault (there is **no** `deleteSecret`) | R2024a |
| `setSecretMetadata` | Attach metadata (e.g. an expiry date, owner) to a secret | R2024a |
| `getSecretMetadata` | Read a secret's metadata as a dictionary | R2024a |
| `secretID` | A reference object carrying a secret's *name*, not its value; accepted by `weboptions` and `matlab.net.http.Credentials` | R2025a |
| `importSecrets` | Load a set of secrets from a file into the vault (no prompt) | R2026a |

## Patterns

### Store once, retrieve at use

```matlab
% One-time, at the MATLAB prompt (prompts for the value — do NOT type the secret in code):
setSecret("MyApiToken");

% In your script, read it only where needed:
token = getSecret("MyApiToken");
```

Optionally record metadata such as an expiry so callers can check freshness before use:

```matlab
% Metadata values are stored in a dictionary; wrap each value in a cell:
setSecretMetadata("MyApiToken", dictionary("Expires", {datetime(2026,12,31)}));

md = getSecretMetadata("MyApiToken");
expiry = md{"Expires"};            % {} indexing returns the stored value
if expiry < datetime("today")
    error("MyApiToken expired on %s — rotate it with setSecret(...,Overwrite=true).", expiry);
end
token = getSecret("MyApiToken");
```

### Rotate or update a secret

`setSecret(...,Overwrite=true)` replaces the value of an existing secret — the normal way to
rotate a credential (replace it with a new value, e.g. periodically or after expiry). Without
`Overwrite`, `setSecret` errors on a name that already exists.

```matlab
setSecret("MyApiToken", Overwrite=true);   % prompts for the new value
```

### REST call with a bearer token

Fetch the token from the vault and set it in the `Authorization` header.

```matlab
token = getSecret("MyApiToken");
opts = weboptions( ...
    HeaderFields = ["Authorization", "Bearer " + token], ...
    ContentType  = "json");
data = webread("https://api.example.com/v1/data", opts);
```

For basic auth, hand `weboptions` a `secretID` so the value is resolved at request time
and never sits in a variable:

```matlab
username = getenv("API_USER");   % REPLACE: your service-account user name
opts = weboptions(Use