Authentication, Regions & Networking

SDK requests return 401 Unauthorized when a token type does not match the SDK/API being used (for example, using a CMA token with the Delivery SDK).

Root Cause

A mismatch exists between the API being called and the token provided, such as using a Management Token for Delivery API calls or a token from a different stack.

Resolution

1. Use the correct token for the SDK:
   • Delivery SDK -> Delivery Token
   • Management SDK -> Management Token / Auth Token
2. Confirm that the API key and token were generated from the same stack.
3. For Delivery SDK calls, verify the token has access to the configured environment.

A fetch call returns 200 with a non-empty payload and no 401 response. Escalate if a token is active in UI but still rejected. Share stack UID, SDK package name/version, and request ID if available.

Content type updates via CMA fail with 403 when the token role/scope/policy does not allow model changes.

Root Cause

The provided token lacks the necessary administrative permissions/roles to modify schemas, or the request originates from an IP address not included in the stack’s allowlist.

Resolution

1. Ensure the token role has content model update permissions (typically admin-level).
2. Confirm IP allowlist/policy permits the calling host.
3. Validate stack limits or governance policies are not blocking changes.

update() returns 2xx, and schema changes appear in UI/API. Escalate if owner/admin role still receives 403; include request ID and sanitized payload.

Some corporate gateways block requests unless expected headers are present or match policy.

Root Cause

Corporate firewalls or security gateways are configured to drop requests that lack specific identification headers or custom security metadata.

Resolution

1. Do not assume SDK omits identification headers by default.
2. If policy requires extra headers, add approved custom headers in your request/plugin layer.
3. Validate upstream proxies are not stripping headers before the request reaches Contentstack.
4. Coordinate with network/security team on allowlist rules for SDK traffic.

Requests return 2xx, and WAF logs confirm expected headers/policy match. Escalate with sanitized gateway logs and request ID when blocked despite compliant headers.

Using default region/host against non-US stacks can produce auth/key mismatch symptoms.

Root Cause

The SDK is defaulting to the US region host while the target stack is hosted in a different region (e.g., EU or AU), causing a "Stack Not Found" or invalid key error.

Resolution

1. Set explicit region in SDK initialization.
2. Use valid region constants supported by the SDK (for example Region.EU, Region.AU, Region.AZURE_NA, Region.AZURE_EU, Region.GCP_NA, Region.GCP_EU in Delivery TS SDK).
3. Ensure API key/token are from the same regional stack.

Region-configured calls return 200 from the correct regional host. Escalate if region is correct but key is still rejected; include stack UID, region, and request host.

Scripts using the SDK with an Authtoken (user session) fail after a few hours, resulting in 401 Unauthorized as the session expires.

Root Cause

User-session Authtokens have a limited lifespan and expire, causing long-running background scripts to fail once the initial session token becomes invalid.

Resolution

Long-running scripts using user session auth can fail when session tokens expire.

Do

1. Use management_token for long-running, non-interactive server jobs.
2. Keep auth mode explicit per workflow (management_token, authtoken, or OAuth bearer).
3. Handle 401 with a controlled re-auth/refresh path, then retry only safe/idempotent operations.
4. Configure retry strategy for 429/5xx separately from authentication renewal.

Don't

1. Don't run long background automation on user authtoken unless you own renewal logic.
2. Don't assume a generic login() call automatically refreshes tokens in every SDK flow.
3. Don't mix authorization and authtoken headers in the same request path.
4. Don't retry 401 indefinitely without rotating or re-establishing credentials.

Long-running job completes without late-stage 401 failures, and any forced token rollover recovers via the defined re-auth path. Escalate with job duration, auth mode (management_token/authtoken/OAuth), retry settings, and first 401 timestamp/request ID.

Users cannot log in to the CLI (csdx auth:login) despite using correct credentials, receiving an "Invalid Credentials" or "MFA Required" error.

Root Cause

Authentication fails due to incorrect region settings in the CLI config, or the user has failed to complete the required Multi-Factor Authentication (MFA) challenge.

Resolution

1. Use csdx auth:login and complete the built-in MFA/OTP flow when prompted (or use --oauth for SSO flows).
2. Confirm configured region before retrying auth (csdx config:get:region / csdx config:set:region).

csdx auth:login succeeds, csdx auth:whoami prints the logged-in email, and csdx config:get:region shows the expected region. Escalate through CLI support path with CLI version, exact login command used, region config output, and auth logs.