--- title: Store Credentials Outside the Database slug: store-credentials-outside-the-database type: how-to plugin: huxx-connect summary: Reference a wp-config.php constant or an environment variable in any credential field so the secret itself never enters the database. keywords: [wp-config, constant, environment variable, credentials, secrets] version_added: 1.2.5 version_updated: 1.2.5 level: advanced related: [understanding-authentication, choose-an-encryption-tier, encryption-tiers, import-and-export-configurations, debug-api-requests] --- HuxxConnect encrypts stored credentials, but you can go further: put the secret in `wp-config.php` or a server environment variable and store only a *reference* to it. The database then holds a harmless name like `HUXX_DOCS_GITHUB_TOKEN`; the real value is resolved on the server at request time. Database dumps, migrations, and [configuration exports](/docs/connect/how-to/import-and-export-configurations/) carry the reference, never the secret. > **Quick version:** > 1. In `wp-config.php`, above the "That's all, stop editing!" line: > `define( 'HUXX_DOCS_GITHUB_TOKEN', 'hxc_example_token_123' ); // Replace with your real token.` > 2. In the credential field (e.g. **Token (or constant name)**), enter the > constant name: `HUXX_DOCS_GITHUB_TOKEN`. > 3. Click **Save API**. The field shows a "wp-config.php constant" hint; > requests send the constant's value. > > Alternative: enter `env:HUXX_DOCS_GITHUB_TOKEN` to read the environment > variable of that name via `getenv()` instead. ## How references are recognized Every credential field accepts two reference forms, resolved in `src/Auth/AuthManager.php` (`resolve_references()`) each time a request is built: - **PHP constant** — a value matching ALL_CAPS naming (`^[A-Z][A-Z0-9_]+$`: starts with a capital letter, then capitals, digits, or underscores). If a constant with that exact name is defined, its value is used. - **Environment variable** — a value starting with `env:`. The remainder is looked up with `getenv()`; if the variable is set, its value is used. Resolution applies to these auth config fields: `token`, `api_key`, `key`, `password`, `secret`, `client_id`, `client_secret`, and `username` — i.e. every credential slot across [Bearer Token](/docs/connect/how-to/authenticate-with-a-bearer-token/), [API Key](/docs/connect/how-to/authenticate-with-an-api-key/), [Basic Auth](/docs/connect/how-to/authenticate-with-basic-auth/), and [OAuth 2.0](/docs/connect/how-to/set-up-oauth2/) (Pro). Endpoint-level Authentication Overrides resolve the same way. Reference strings are recognized on save (`is_externally_referenced()` in `src/Storage/ApiRepository.php`) and stored as-is — not encrypted, not masked — because they contain no secret. ## Use a wp-config.php constant 1. Define the constant in `wp-config.php`, above the `/* That's all, stop editing! */` line: ```php define( 'HUXX_DOCS_GITHUB_TOKEN', 'hxc_example_token_123' ); // Replace with your real token. ``` 2. Go to **HuxxConnect → APIs**, click **Configure** on the API, and enter the constant name in the credential field — for Bearer Token auth that is **Token (or constant name)**: ``` HUXX_DOCS_GITHUB_TOKEN ``` 3. The field's helper text confirms the reference: "wp-config.php constant — not included in database migrations". Click **Save API**. Requests now send the constant's *value*, not its name: ``` GET /repos/huxxco/huxx-connect HTTP/1.1 Host: api.github.com Authorization: Bearer hxc_example_token_123 ``` ## Use an environment variable Prefix the variable name with `env:` in the same field: ``` env:HUXX_DOCS_GITHUB_TOKEN ``` The variable must be visible to PHP via `getenv()` when WordPress handles web requests. With PHP-FPM that means the pool config (note that FPM's `clear_env = yes` default strips inherited variables): ```ini ; /etc/php/8.2/fpm/pool.d/www.conf env[HUXX_DOCS_GITHUB_TOKEN] = hxc_example_token_123 ; Replace with your real token. ``` After reloading PHP-FPM, requests send the variable's value — the same output as the constant example above. ## Edge cases - **Unresolved references are sent literally.** If the constant isn't defined (or the env var isn't set), resolution skips the field and the literal string — e.g. `HUXX_DOCS_GITHUB_TOKEN` — is sent as the credential. The API rejects it; see below. - **All-caps secrets look like references.** A real credential that happens to match `^[A-Z][A-Z0-9_]+$` (e.g. `ABCD1234`) is treated as a constant reference and stored unencrypted. As long as no constant with that name exists it is still sent correctly, but it bypasses encryption — for such a key, define a constant and reference it instead. - **Per-environment values come free.** Because only the name is stored, staging and production can define different values for the same constant — no config changes when the database moves between them. ## If it didn't work - **`401` and the provider log shows your constant name as the credential.** The reference didn't resolve. For constants: check the exact spelling in `wp-config.php` and that the `define()` sits above "That's all, stop editing!". For `env:` references: confirm `getenv()` sees the variable under the web server user (FPM `clear_env` is the usual culprit) — CLI and web contexts often differ. Confirm what was sent with [Debug API requests](/docs/connect/how-to/debug-api-requests/). - **The reference resolves in WP-CLI but not in the browser (or vice versa).** Environment variables are per-process: the CLI inherits your shell, the web request inherits PHP-FPM's pool config. Set the variable in both places, or switch to a `wp-config.php` constant, which is loaded identically in every context. - **The field shows a broken-credentials warning after switching to a reference.** The warning applies to encrypted values, not references — make sure the field contains only the reference string (no quotes, no whitespace) so HuxxConnect recognizes it. For a constant, the "wp-config.php constant" hint below the field confirms recognition; an `env:` reference shows no hint (the standing helper text stays put) even though it is recognized on the server.