Skip to navigation

Use saved credentials in code

View as Markdown

When your code scripts or code workflows call external APIs using MCP.Atomicwork.executeHttpRequest, you can reference saved credentials by name instead of putting secrets in your code. Two helpers make this work:

HelperSignatureUsed for
aw.secretaw.secret(credential, { field })A JSON or form body field value
aw.secretHeaderaw.secretHeader(credential, { prefix, suffix, field })A header value, optionally wrapped in text

Before using these helpers, save the credential in Settings > Organization > Security > Credential store with its allowed hosts. See Managing credentials for setup, credential types, and allowed-host rules.

Parameters

  • credential — the saved credential’s name (recommended) or its numeric ID. Names survive re-creating a credential, so prefer them.
  • field — selects a top-level key from a JSON credential, such as client_id. Without it, you get the whole value. Nested keys like client.id are not supported.
  • prefix / suffix (aw.secretHeader only) — header-safe text up to 256 characters, such as "Bearer " or "SSWS ". You can’t concatenate a secret with + or use it in a template string — use prefix/suffix instead.
  • Basic auth with no field — aw.secretHeader sends base64(username:password). You can also select the username or password field individually.

Where they work

Put the secret in…Code Library scriptsCode workflows
A header of executeHttpRequestYesYes
A JSON or form field of executeHttpRequestYesYes
A header of fetchUse executeHttpRequestYes

All HTTP methods work: GET, POST, PUT, PATCH and DELETE. Up to 8 secret headers and 16 secret body fields per request.

Code Library scripts are plain JavaScript — leave out type annotations like (res: any), and end the script with return await main();. Code workflows are TypeScript.

Code recipes

Bearer token in a header

const res = await MCP.Atomicwork.executeHttpRequest({
url: "https://acme.okta.com/api/v1/users/me",
method: "GET",
headers: [
{ key: "Authorization", value: aw.secretHeader("okta-api-token", { prefix: "SSWS " }) },
],
});

Microsoft Entra app token, then Microsoft Graph

A two-step flow: exchange client credentials for an access token, then use that token to call the Graph API. The access token comes from a response, so it’s ordinary data — only the saved credentials in the first call need aw.secret.

const tokenRes = await MCP.Atomicwork.executeHttpRequest({
url: "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token",
method: "POST",
headers: [
{ key: "Content-Type", value: "application/x-www-form-urlencoded" },
],
form: {
grant_type: "client_credentials",
client_id: aw.secret("azure-app", { field: "client_id" }),
client_secret: aw.secret("azure-app", { field: "client_secret" }),
scope: "https://graph.microsoft.com/.default",
},
});
const accessToken = JSON.parse(tokenRes.data.body).access_token;
const org = await MCP.Atomicwork.executeHttpRequest({
url: "https://graph.microsoft.com/v1.0/organization",
method: "GET",
headers: [{ key: "Authorization", value: "Bearer " + accessToken }],
});

Don’t log or return access tokens from token endpoints — console.log(res) on a token call writes the token to the run log.

Basic auth

const res = await MCP.Atomicwork.executeHttpRequest({
url: "https://api.vendor.com/v1/data",
method: "GET",
headers: [
{ key: "Authorization", value: aw.secretHeader("vendor-basic", { prefix: "Basic " }) },
],
});

A Basic-auth credential with no field is sent as base64(username:password).

Several values from one JSON credential

Use an “API key holding JSON” credential to keep related values together, then pull each field by name:

form: {
client_id: aw.secret("vendor-app", { field: "client_id" }),
client_secret: aw.secret("vendor-app", { field: "client_secret" }),
audience: "https://api.vendor.com",
}

Two credentials in two headers

headers: [
{ key: "Authorization", value: aw.secretHeader("vendor-api-key", { prefix: "Bearer " }) },
{ key: "X-Tenant-Key", value: aw.secretHeader("vendor-tenant-key") },
]

Supported and not supported

PatternSupportedAlternative
Secret in a URL path or query stringNo — URLs appear in proxy and access logsSend it in a header with aw.secretHeader
Secret joined to other text ("Bearer " + secret, template strings)No — code never holds the valueHeaders: use prefix / suffix. Body: use the secret as the whole field value
Secret in a raw text, XML or SOAP bodyNo — only JSON and form fields can be filled in safelySend the body with fetch and the key in a header with aw.secretHeader
Secret in a fetch body or JSON.stringifyNoUse executeHttpRequest with json or form
fetch with a secret in a Code Library scriptNo — scripts send HTTP through executeHttpRequestUse executeHttpRequest
Signing requests (HMAC, AWS SigV4, signed JWT, certificate auth)No — signing needs the raw secret inside the codeAsk the platform team for a native integration
Challenge-response auth (Digest, NTLM, Kerberos)No — computed from the secret inside the clientUse the vendor’s token or API-key auth
Client certificates (mutual TLS)No — the credential store holds keys, not certificatesAsk the platform team
More than 8 secret headers or 16 body fields per requestNoSplit into separate calls
Nested JSON field (client.id)No — fields are top-level keysSave the JSON flat: {"client_id": …}
Apps already connected under IntegrationsUse the connection’s own authCall them with API.<app>… via Call API; use saved credentials only for APIs without a connector

Move existing code over

  1. Find keys in your scripts: look for Bearer , SSWS , client_secret, api_key, password and long random strings.
  2. Create a credential for each one in Settings > Organization > Security > Credential store, with its allowed hosts.
  3. Replace each key with aw.secretHeader (headers) or aw.secret (body fields).
  4. Test once, then publish.
  5. Rotate the old key at the vendor — it was in code, so treat it as exposed.

Before:

headers: [{ key: "Authorization", value: "SSWS 00aBc…" }]

After:

headers: [{ key: "Authorization", value: aw.secretHeader("okta-api-token", { prefix: "SSWS " }) }]

Tell a refused request from a vendor error

A request that fails the credential check comes back with the same shape as a vendor error. The body tells them apart:

const res = await MCP.Atomicwork.executeHttpRequest({
url: "https://acme.okta.com/api/v1/users/me",
method: "GET",
headers: [{ key: "Authorization", value: aw.secretHeader("okta-api-token", { prefix: "SSWS " }) }],
});
let body = {};
try { body = JSON.parse(res.data.body); } catch (e) {}
const refused = body.message === "Credentials not allowed on this URL"
|| body.message === "Webhook execution failed.";
if (refused) return { ok: false, reason: "credential check failed: check the name, field and allowed hosts" };
if (res.data.status_code !== 200) return { ok: false, vendor_status: res.data.status_code };
return { ok: true, user_id: body.id };

Errors

From your code (before the request leaves)

These throw at the offending line before anything is sent. Wrap the call in try/catch if you want to return a message instead.

Error messageCauseFix
aw.secret(...) is not a string: use it as a whole json or form value…Placeholder joined to text, put in a URL, or used in a template stringUse it as a whole field value; in headers use aw.secretHeader with prefix
aw.secret(...) can only be used as a json or form value of MCP.Atomicwork.executeHttpRequest…Placeholder in a fetch body, JSON.stringify or another toolUse executeHttpRequest with json or form
aw.secretHeader(...) is not a string: use it as the whole value of a header entry…Header placeholder joined to text, or put in a fetch header in a Code Library scriptUse prefix/suffix; in Code Library scripts use executeHttpRequest
aw.secret is for json or form values; in headers use aw.secretHeader(credential, { prefix, field })aw.secret used as a header valueSwitch to aw.secretHeader
aw.secretHeader is for header values; in json or form use aw.secret(credential, { field })aw.secretHeader used in a bodySwitch to aw.secret
Too many secret headers (at most 8)More than 8 secret headers in one requestSplit the call
Too many credential referencesMore than 16 secret body fields in one requestSplit the call

From the request check (nothing was sent)

ResponseCauseFix
403 with "Credentials not allowed on this URL"The credential name isn’t in your tenant, the field doesn’t exist (including nested fields like client.id), the host isn’t allowed, the URL uses http:// or a port other than 443, or the credential has no allowed hosts yetCheck the name, field and allowed hosts in Settings > Organization > Security > Credential store, and use https://
400 with "Webhook execution failed."The same header set both as a secret and literally (any letter case), a reserved header like Host or Proxy-Authorization, an object inside form, or a body on a GETSet each header once; use a normal auth header; use json for nested data; send bodies with POST, PUT or PATCH

From the vendor (the request was sent)

ResponseCauseFix
401/403 with the vendor’s own body (e.g. invalid_client)The saved value is wrong, expired or lacks permissionUpdate the credential’s value in the store or the vendor-side permissions
3xx with a Location headerThe API redirected; executeHttpRequest does not follow redirectsCall the final URL directly

Learn more