lambda stack -- enter the AWS secret via a local, untracked file; never paste real secrets into chat

celigo stacks create < lambda-stack.json

Example `lambda-stack.json` (use a placeholder here and supply the real key only in a local file or the UI):

```json
{
  "name": "Order Enrichment Lambda",
  "type": "lambda",
  "framework": "twoDotZero",
  "lambda": {
    "accessKeyId": "<aws-access-key-id>",
    "secretAccessKey": "<aws-secret-access-key>",
    "awsRegion": "us-east-1",
    "functionName": "celigo-order-enrichment",
    "language": "Node.js"
  }
}

5. Wire up authentication

• server -- the systemToken is generated on creation. Retrieve the unmasked value from the UI (the stack's "Show token" action) or with celigo stacks token <id>, then set it as the INTEGRATOR_EXTENSION_SYSTEM_TOKEN environment variable on every server that runs the extension code. To rotate it, run celigo stacks rotate-token <id> (the old token is invalidated immediately) and re-fetch the new one. Both commands print or replace a secret, so have the user run them where the value goes straight into the server's environment, not into a chat.
• lambda -- the AWS IAM user behind accessKeyId / secretAccessKey must have the lambda:InvokeFunction permission for the target function, and awsRegion must match where the function is deployed.

6. Point a hook or wrapper at the stack

The stack only runs code once referenced:

• Hook -- deploy the hook function to the stack's runtime, then set _stackId on the hook definition on the export/import in place of _scriptId, with function naming the deployed function. A hook can't be patched on its own, so this is a full update of the export or import: read it, change only the hook (remove _scriptId, add _stackId, set function), and write the whole document back. Leave the script itself alone unless the user asks; other steps may still use it. See writing-scripts > How to Write a Script for hook wiring.
• Wrapper connection -- set wrapper._stackId on the wrapper connection, and wrapper.pingFunction to the function your extension exposes for the connection test (Test Connection, or celigo connections ping <id>, calls it). See configuring-connections > Connection Types.

7. Verify

Confirm the expected hooks and wrapper connections reference the stack before relying on it:

celigo stacks get <id>
celigo stacks dependencies <id>    # the live list, including wrapper connections

CLI Commands

# CRUD
celigo stacks list
celigo stacks get <id>
celigo stacks create < stack.json
celigo stacks update <id> --file stack.json --force   # the GET body, masks left as read (Gotcha 5)
celigo stacks delete <id> [-y]

# Token and dependents (the token is server stacks only)
celigo stacks token <id>               # prints the unmasked systemToken -- keep it out of chat
celigo stacks rotate-token <id> [-y]   # old token invalid immediately; re-run `token`
celigo stacks dependencies <id>        # hooks and wrapper connections using the stack
celigo stacks audit <id>

# Discover existing stacks across the account
celigo account search "<keyword>"

celigo stacks token and rotate-token call GET and DELETE /v1/stacks/{id}/systemToken; the UI's "Show token" action is the alternative.

Pre-Submit Checklist

• Confirmed a stack is genuinely needed (heavier/specialized code, compliance, or a custom connector wrapper) -- not a routine hook the hosted runtime could handle.
• Correct type chosen (server vs lambda) based on where the team operates infrastructure.
• framework set to twoDotZero.
• server: hostURI is reachable over HTTPS; a firewall in front of it allows Celigo's published addresses (configuring-connections > Partner IP allow lists), not the deprecated ipRanges.
• server: systemToken retrieved (not set) and configured as INTEGRATOR_EXTENSION_SYSTEM_TOKEN on the runtime.
• lambda: awsRegion, functionName, and AWS keys supplied; IAM user has lambda:InvokeFunction.
• No secret pasted into chat or a tracked file; AWS secretAccessKey entered via the UI or a local, untracked file only.
• The consuming hook (_stackId on the export/import hook) or wrapper connection (wrapper._stackId, with wrapper.pingFunction set) actually points at this stack.
• An update sends the stack as read, masks included (celigo stacks update <id> --file stack.json --force), never with secretAccessKey left out.
• Dependents verified so you know exactly what runs on the stack.

Gotchas

1. A stack is the runtime, not the code. It does nothing visible until a hook or wrapper references it via _stackId. Creating a stack alone changes no behavior.
2. Most accounts don't need one. Hooks run on Celigo's hosted JavaScript runtime by default. Only escalate to a stack on a real trigger.
3. The server systemToken is auto-generated -- you don't set it. Retrieve it with celigo stacks token <id> (or the UI), store it as INTEGRATOR_EXTENSION_SYSTEM_TOKEN on your server, and rotate with celigo stacks rotate-token <id> when needed.
4. Never paste secrets into chat. Both the systemToken and the AWS secretAccessKey are secrets returned masked as ******. A secret pasted into a logged conversation is compromised -- rotate it (recycle the system token, or rotate the AWS key) and re-enter it via the UI.
5. An update sends the secrets back as their masks. A GET returns lambda.secretAccessKey and server.systemToken as ******. On a PUT the mask keeps the stored AWS secret, and leaving secretAccessKey out is refused (422 secretAccessKey is not provided for the stack of type lambda.). server.systemToken is ignored whatever the body holds, so only rotate-token changes it. To change the AWS secret, send the new value from a local, untracked file.
6. PUT clears omitted optional fields. Updating a stack replaces it: for example, omitting framework on update clears a previously set value. GET the stack, modify, then PUT the full object: celigo stacks update <id> --file stack.json --force. The CLI's mask check refuses that body without --force, and celigo stacks set refuses every stack, since both types come back masked.
7. twoDotZero is the only supported framework version. There is no other valid value.
8. lambda needs lambda:InvokeFunction. The IAM user must be allowed to invoke the function, functionName (name or ARN) must exist in the specified awsRegion, and language must match the deployed function.
9. Stack != on-premise agent. Don't create a stack to reach a private database -- that's connectivity, which is an on-premise agent's job. A stack is compute for your code.
10. Delete is a soft delete (30-day recycle bin), and dependents block it. A stack still referenced by hooks or wrapper connections cannot be deleted until those references are repointed or removed.
11. A hook names one runtime, and the API won't choose for you. A hook saved with both _scriptId and _stackId answers 200 and stores both. When moving a hook onto a stack, remove _scriptId in the same update, and set function to the stack's function name.
12. A stack belongs to one environment. Each environment keeps its own resources, so the hooks and wrappers in a sandbox need a stack registered in that sandbox, with its own system token (or AWS keys) on the runtime it points at. celigo promote never copies a stack: it binds each one to the target's single stack of the same name and type, or the one you pin with --map, and otherwise refuses unless --create-connections makes a credential-less shell there for you to finish.

Common Errors