Marigold Insights | Citizen Volunteer Network

The Dual-Layer Mesh

Given the sensitive nature of civic auditing workloads, relying solely on Bearer tokens is mathematically insufficient. If an administrative token is accidentally leaked in a GitHub repository or compromised via a social engineering vector, unauthorized ingress must still be mitigated.

Therefore, Marigold mandates a Dual-Layer Mesh:

Layer 1: Network ACLs

Tokens only function when the API request originates from a pre-approved, static IP block registered to your state agency. Dynamic residential IPs and standard public cloud shared IPs are blocked at the Web Application Firewall (WAF) layer.

Layer 2: Token Entropy

Each HTTP request must include an Authorization: Bearer header containing a 256-bit cryptographically secure pseudo-random string tied specifically to an isolated audit instance (Session Token).

Implementing the Authorization Header

Your integration must append the following HTTP header to all requests against the https://api.marigoldinsights.org/v1 space. Do not use Basic Auth or query parameter authentication. We do not support it.

HTTP Header

1Authorization: Bearer mg_live_x89aZ120BklqP94MnvX5...

Token Prefix Definitions

Marigold utilizes explicit token prefixing to prevent accidental leakage in logging systems. If your APM or SIEM detects a string starting with these prefixes in plaintext logs, it should immediately trigger a P1 security incident.

Prefix	Environment	Description
mg_live_	Production	Grants access to live algorithmic clusters. Metered against your agency's SOC 2 compliance SLA.
mg_test_	Staging / QA	Used strictly for unit testing. Automatically overrides payloads with synthetic anomalies to prevent data contamination.
mg_rot_	Administrative	A high-privilege token used exclusively to hit the `/tokens/rotate` endpoint. Never use this for data sweeps.

Key Rotation Strategy (Zero-Downtime)

We mandate a 30-day strict rotation policy for all mg_live_ tokens. If a token exceeds 30 days of age, our ingress routers will intercept the request and return a 401 Unauthorized - ERR_TOKEN_EXPIRED.

To maintain zero-downtime, your DevOps infrastructure must automate the token rotation utilizing the mg_rot_ administrative credential. When you request a new live token, the legacy token enters a 72-hour graceful deprecation window. During this window, both the old and new token will successfully authenticate, allowing your monolithic applications time to fetch the newly provisioned token from your internal secrets manager without dropping active algorithmic sweeps.

Automated Rotation Example (Bash / Cron)

Automated Rotation Script

1#!/bin/bash
2# Triggered via Jenkins or GitHub Actions every 25 days
3
4# 1. Request new token from Marigold
5NEW_TOKEN_JSON=$(curl -X POST https://api.marigoldinsights.org/v1/tokens/rotate \
6  -H "Authorization: Bearer $MARIGOLD_ROT_TOKEN")
7
8NEW_TOKEN=$(echo $NEW_TOKEN_JSON | jq -r '.new_live_token')
9
10# 2. Push to your internal AWS Secrets Manager
11aws secretsmanager put-secret-value \
12  --secret-id prod/marigold/bearer \
13  --secret-string "$NEW_TOKEN"
14
15echo "Rotation complete. Legacy token expires in 72 hours."

Handling 401 & 403 Errors

It is critical that your application differentiates between a 401 (Authentication) and a 403 (Authorization/Network) failure.

401 Unauthorized: The WAF successfully received the request, but the token itself was malformed, expired, or failed signature validation. Your application should attempt to fetch the latest token from your secrets manager and retry once.
403 Forbidden: The token is mathematically valid, but Layer 1 (NACL) rejected the request. Your server's egress IP has shifted. Do not retry automatically; this requires manual network administrator intervention to update the IP whitelist with Marigold Support.

Authentication & Tokens