Question 1

Where and how do I generate API keys for programmatic automation?

Accepted Answer

API keys are generated exclusively within the authenticated Amaris Dashboard under Settings > API Keys (/client/api-keys). In accordance with strict security standards, documentation pages explain integration architecture but never issue or display live tokens. Once generated, your secret key is revealed once and stored on the server exclusively as a cryptographic SHA-256 hash.

Question 2

What is the difference between Live Mode (amaris_live_) and Test Mode (amaris_test_) keys?

Accepted Answer

Amaris enforces strict environment separation modeled after Stripe:

• Live Mode (amaris_live_...): Authorizes production environments. Changes modify live customer websites, dispatch real webhooks, and draw from your paid Production Credit balance.
• Test Mode (amaris_test_...): Authorizes local development, CI/CD automated test suites, and staging environments. Simulates crawl cycles and AST dry-runs without billing credits or altering production servers.

Question 3

How do I authenticate HTTP REST API requests in cURL, Node.js, and Python?

Accepted Answer

Include your API key in the standard HTTP Authorization header using the Bearer scheme over TLS 1.3:

`Authorization: Bearer amaris_live_YOUR_KEY`

Example cURL:
`curl -X GET https://amarisbrand.com/api/v1/seo-autopilot -H "Authorization: Bearer amaris_live_..." -H "Content-Type: application/json"`

In Node.js, pass the header via `fetch(url, { headers: { Authorization: "Bearer " + process.env.AMARIS_API_KEY } })`.

Question 4

What granular scopes are available for restricting token permissions?

Accepted Answer

Amaris supports fine-grained permission scoping:

• seo:read: Read crawl data, audit reports, and visibility scores.
• seo:write: Update meta tags, schema configs, and site connection settings.
• autopilot:execute: Trigger AST code transforms, staging PRs, and production deploys.
• brand:generate: Invoke Brand Studio naming, voice, and design token generators.
• reports:export: Download executive PDF decks and white-label CSV audits.
• webhooks:manage: Create, update, and test webhook endpoint subscriptions.

Question 5

What rate limits are enforced and what headers should developers inspect?

Accepted Answer

Enterprise plans provide up to 1,000 requests per minute, while Starter tiers provide 60 req/min. Every response returns rate limiting telemetry:

• X-RateLimit-Limit: Quota allocated in the current window.
• X-RateLimit-Remaining: Remaining calls in the current window.
• X-RateLimit-Reset: Unix timestamp when the quota resets.

When exceeded, the server returns HTTP 429 Too Many Requests with a Retry-After header.

Question 6

How do Webhooks work and how do I verify HMAC signatures?

Accepted Answer

Webhooks deliver real-time JSON events (e.g. audit.completed, deployment.approved, rollback.triggered) to your destination HTTPS URL. Each delivery includes an HMAC-SHA256 signature in the X-Amaris-Signature header computed using your webhook signing secret (whsec_...). Your server verifies authenticity by computing crypto.createHmac("sha256", secret).update(rawPayload).digest("hex") and comparing it with the header.

Question 7

Why should secret API keys be generated inside a secure dashboard rather than public documentation?

Accepted Answer

API keys are cryptographic credentials that grant full programmatic access to account resources:

• Security Protection: Generating keys inside authenticated dashboards ensures they are tied to verified user sessions with strict MFA (Multi-Factor Authentication).
• Public Docs are Educational: Documentation examples must only display dummy placeholder keys (e.g. `sk_live_...`) to prevent users from exposing real tokens in browser caches or shared networks.
• One-Time Display: Secure dashboards only show secret keys once upon creation, storing only hashed values on the database.

Question 8

What is the difference between public client publishable keys and secret backend API keys?

Accepted Answer

Separating key types protects backend database access:

• Public / Publishable Keys (`pk_live_...`): Safe to include in client-side JavaScript, mobile apps, and frontend code. Severely restricted to non-sensitive actions (e.g. rendering a payment element or loading public catalog data).
• Secret / Private Keys (`sk_live_...`): Full administrative permissions to charge credit cards, query database tables, and modify account settings. Must NEVER be exposed in frontend code; keep strictly on secure servers.

Question 9

How do you securely store and inject API keys in production environments using .env and KMS?

Accepted Answer

Production secrets management eliminates hardcoded credentials:

• Environment Variables: Store secrets in local `.env.local` files and strictly exclude them in `.gitignore`.
• Cloud Key Management (AWS KMS, GCP Secret Manager, Vault): Encrypt secrets at rest and inject them dynamically into runtime container environments.
• Platform Environment Secrets: Use platform-native encrypted secret managers (Vercel Project Environment Variables, GitHub Actions Encrypted Secrets).

Question 10

What should you do immediately if an API key is accidentally committed to a public GitHub repo?

Accepted Answer

Execute an immediate emergency credential revocation protocol:

1. Revoke the Compromised Key: Open your dashboard and immediately delete/revoke the leaked token to invalidate further unauthorized requests.
2. Generate a Replacement Key: Create a new key and update production environment variables.
3. Audit Activity Logs: Inspect API telemetry logs to review what requests and data reads were performed using the compromised token.
4. Git Purge: Use tools like `git-filter-repo` or BFG Repo-Cleaner to permanently scrub the secret from Git commit history.

Question 11

How does API key rotation work without causing zero-downtime outages in live applications?

Accepted Answer

Zero-downtime key rotation uses dual-key overlapping windows:

1. Generate Secondary Key: The dashboard issues a new active secondary key while keeping the existing primary key active.
2. Update Application Configs: Deploy the new secondary key across server clusters.
3. Verify Traffic: Monitor logs to confirm that all production requests have transitioned to the new key.
4. Deprecate Old Key: Once zero traffic hits the old key, permanently revoke it in the dashboard.

Question 12

Why should API keys have custom descriptive labels and expiration dates?

Accepted Answer

Key hygiene practices prevent forgotten orphan credentials:

• Descriptive Labels: Naming keys by service and environment (e.g. `Shopify-Sync-Production-US`) allows team members to identify who generated the key and what application depends on it.
• Automated Expiration: Enforcing 90-day or 1-year expiration policies forces scheduled credential rotation, mitigating the risk of compromised legacy keys remaining active indefinitely.

Question 13

What is key fingerprinting and prefixing (e.g., sk_live_, pk_test_) and why is it industry standard?

Accepted Answer

Prefixing tokens (pioneered by Stripe and GitHub) improves security scanning:

• Instant Environment Identification: Developers and log parsers instantly know whether a token belongs to live production (`sk_live_`) or safe test sandbox (`sk_test_`).
• Automated Secret Scanning: GitHub and GitGuardian scan public repositories for known prefixes (`sk_live_`) and automatically alert the provider to revoke leaked keys in seconds.

Question 14

How do you restrict API keys by IP address allowlist or HTTP referrer domain?

Accepted Answer

Key restriction policies establish perimeter defense:

• IP Address Allowlisting: Restrict secret API keys to only accept requests originating from dedicated static server IP addresses (e.g. your AWS NAT Gateway IPs), instantly blocking stolen keys from being used elsewhere.
• HTTP Referrer Restrictions: Restrict public frontend keys to execute only from your authorized domain names (`https://yourbrand.com/*`).

Question 15

What is the purpose of test mode sandbox environments in developer APIs?

Accepted Answer

Sandbox environments provide a fully functional, simulated replica of an API platform:

• Safe Experimentation: Developers can create fake users, simulate orders, test failure retries, and write automated test suites without spending real money or modifying live customer data.
• Speed: Sandboxes offer instant provisioning with mock databases that can be reset to clean states at any time.

Question 16

How do test mode API keys simulate successful, failed, and edge-case API responses?

Accepted Answer

Modern APIs support test triggers via magic tokens and request headers:

• Magic Test Values: Submitting specific test numbers (e.g. credit card `4000 0000 0000 0002` to simulate a card decline, or `4000 0000 0000 0077` to trigger a 3D Secure challenge).
• Custom Test Headers: Sending headers like `X-Simulate-Error: 500` or `X-Simulate-Delay: 5000` to test how your client application handles network timeouts and server failures.

Question 17

Can test mode transactions ever charge real money or affect production customer databases?

Accepted Answer

No. High-assurance platforms maintain complete physical or logical separation:

• Isolated Data Stores: Test mode data lives in separate sandbox databases completely isolated from live production tables.
• Simulated Gateways: Payment integrations connect to dummy banking simulators that never interact with credit card networks or bank clearinghouses.

Question 18

How do developers toggle between staging sandbox and live production in client SDKs?

Accepted Answer

Switching environments requires only changing the initialized API key or endpoint URL:

```typescript
import { AmarisClient } from '@amaris/sdk';

// Development / Staging
const client = new AmarisClient({ apiKey: process.env.AMARIS_TEST_KEY });

// Production
const client = new AmarisClient({ apiKey: process.env.AMARIS_LIVE_KEY });
```
• The SDK automatically detects the `_test_` or `_live_` key prefix and routes requests to the corresponding environment.

Question 19

What test credit card numbers and mock data are used for sandbox payment verification?

Accepted Answer

Standard test credit card benchmarks used across payment APIs:

• Successful Payment: `4242 4242 4242 4242` with any future expiry date and 3-digit CVC.
• Card Declined: `4000 0000 0000 0002` (generic decline) or `4000 0000 0000 0005` (insufficient funds).
• 3D Secure Authentication: `4000 0000 0000 3063` (triggers interactive SMS challenge modal).

Question 20

How do you test webhooks locally on your computer using Stripe CLI, ngrok, or webhook.site?

Accepted Answer

Testing webhooks on localhost requires exposing a local port to the internet:

• Native CLI Forwarding: Use the platform CLI (e.g. `stripe listen --forward-to localhost:3000/api/webhooks`) which establishes a secure WebSocket tunnel directly to your local development server.
• ngrok: Run `ngrok http 3000` to generate a public HTTPS forwarding URL.
• Webhook.site: Paste a temporary webhook inspector URL to inspect raw JSON headers and payloads in a visual browser UI.

Question 21

What automated tests should run against sandbox endpoints before switching to live mode?

Accepted Answer

Run end-to-end integration test suites in CI before releasing live API keys:

1. Happy Path Flow: Complete a full transaction, verify database state, and confirm success response.
2. Webhook Verification: Verify that your local webhook handler verifies HMAC signatures and updates database models.
3. Error & Rate Limit Handling: Verify that client retries handle simulated HTTP 429 and 500 errors gracefully.

Question 22

Why do financial and telecom APIs require KYC verification before unlocking live mode keys?

Accepted Answer

Live production APIs interact with real money and telecommunications networks:

• Anti-Money Laundering (AML): Financial regulations (FinCEN, FCA) mandate identity verification (Know Your Customer) to prevent fraud and illicit funds transfers.
• Carrier Spam Regulations: Telecom APIs (Twilio) require 10DLC brand registration to prevent automated SMS spam and protect consumer privacy.

Question 23

What is HTTP Bearer Token authentication and how does the Authorization header work?

Accepted Answer

Bearer Token authentication is an HTTP authentication scheme where the client passes a token in the request header:

`Authorization: Bearer <token_value>`

• 'Bearer' Meaning: Any party that 'bears' or holds the token is granted access, eliminating the need to send username and password on every request.
• Transport Security: Because Bearer tokens are bearer credentials, they must be transmitted exclusively over encrypted HTTPS (TLS 1.3) connections.

Question 24

Why is TLS 1.3 mandatory for modern secure API communications?

Accepted Answer

TLS 1.3 is the newest cryptographic security protocol providing major speed and security improvements:

• Removed Insecure Ciphers: Completely deprecates broken legacy ciphers (RSA key exchange, SHA-1, RC4, CBC mode).
• Perfect Forward Secrecy (PFS): Mandates ephemeral Diffie-Hellman, ensuring that if a server's private key is compromised in the future, past recorded traffic cannot be decrypted.
• 0-RTT Faster Handshakes: Reduces the initial connection handshake from two round trips down to one (1-RTT), saving 50-100ms on mobile connections.

Question 25

What is the difference between Bearer API tokens, Basic Auth, and OAuth2 access tokens?

Accepted Answer

Comparing primary API authentication schemes:

• HTTP Basic Auth: Sends `Base64(username:password)` in headers. Legacy method; insecure if credentials are stored in frontend code.
• Static Bearer API Keys: Long-lived opaque strings generated in dashboards. Best for server-to-server microservice communication.
• OAuth2 Access Tokens: Short-lived tokens (JWTs) issued via consent grants (Authorization Code flow). Ideal when third-party apps need bounded access to user data without knowing the user's password.

Question 26

How do API gateways validate Bearer tokens before forwarding requests to microservices?

Accepted Answer

API gateways (Kong, Envoy, Cloudflare) authenticate requests at the edge:

1. Header Extraction: Extracts the token from the `Authorization: Bearer` header.
2. In-Memory Cache Lookup: Checks Redis or local cache to verify key validity and rate limit quotas.
3. Context Injection: If valid, the gateway injects trusted internal headers (e.g. `X-Organization-Id: 402`) and forwards the request to internal microservices.

Question 27

What happens when an expired or malformed Bearer token is submitted to an API endpoint?

Accepted Answer

The API immediately returns an HTTP 401 Unauthorized status response:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "token_expired",
    "message": "The provided API key has expired. Please generate a new key in your dashboard."
  }
}
```
• Response Header: The server should include the `WWW-Authenticate: Bearer error="invalid_token"` header.

Question 28

How do you protect API tokens from being intercepted via man-in-the-middle (MITM) attacks?

Accepted Answer

Preventing MITM interception requires end-to-end transport protections:

• Enforce Strict HTTPS: Configure HSTS (`Strict-Transport-Security: max-age=31536000; includeSubDomains`) so browsers never connect over plain HTTP.
• Certificate Pinning: Mobile applications pin the server's public key certificate, preventing attackers from decrypting traffic with rogue root certificates.

Question 29

What is Mutual TLS (mTLS) and when is it required for enterprise server communication?

Accepted Answer

Mutual TLS (mTLS) enforces two-way cryptographic authentication:

• Standard TLS: Only the client verifies the server's identity.
• Mutual TLS: Both the client and server present and cryptographically verify each other's X.509 digital certificates.
• Enterprise Use Cases: Required in open banking, healthcare integrations, and zero-trust microservice meshes (Istio) to prevent rogue internal services.

Question 30

Why should sensitive credentials and API keys never be passed in URL query parameters?

Accepted Answer

Passing tokens in query strings (`?api_key=secret`) creates catastrophic security leaks:

• Server Access Logs: URLs are recorded in plain text in Nginx, Cloudflare, and AWS access logs.
• Browser History & Referrer Headers: Query parameters persist in browser history and are leaked to external websites via the HTTP `Referer` header.
• Best Practice: Always pass credentials in HTTP headers (`Authorization`) or encrypted request bodies.

Question 31

What is the Principle of Least Privilege (PoLP) in API token security?

Accepted Answer

The Principle of Least Privilege dictates that every module, user, and API token must be granted only the minimum permissions necessary to perform its specific task:

• Blast Radius Containment: If an API token used strictly for read-only analytics is compromised, attackers cannot delete databases or alter billing settings.
• Scoped Generation: Never generate master admin keys when a fine-grained token with specific read scopes is sufficient.

Question 32

What is the difference between read, write, execute, and admin API scopes?

Accepted Answer

Granular scopes segment operational permissions:

• `read` (GET): View resources without modifying them (e.g. `audit:read`, `analytics:read`).
• `write` (POST/PATCH): Create or update resources (e.g. `metadata:write`).
• `delete` (DELETE): Permanently remove records; typically restricted to organization owners.
• `admin` (*): Full administrative control including user management, billing, and key generation.

Question 33

How do modern platforms enforce role-based and scope-based permissions on REST endpoints?

Accepted Answer

Middleware checks token scopes against route permission requirements:

```typescript
// Example Route Middleware
export async function POST(req: Request) {
  const token = await authenticate(req);
  if (!token.hasScope('campaigns:write')) {
    return NextResponse.json({ error: 'Forbidden: Missing campaigns:write scope' }, { status: 403 });
  }
  // Proceed with creation...
}
```

Question 34

Can an API token be scoped to only a single project, organization, or resource ID?

Accepted Answer

Yes. Resource-level scoping restricts access to specific entity IDs:

• Resource ARN/URI Scopes: Tokens include claims like `scope: ['project:proj_8921:read', 'project:proj_8921:write']`.
• Tenant Boundary Protection: Even if a client possesses a valid API key, the authorization engine verifies that the requested resource ID matches the token's authorized scope list.

Question 35

How do you design an intuitive permission matrix for multi-user software applications?

Accepted Answer

Structure permissions as an orthogonal 2D matrix:

• Rows (Entities): Workspaces, Audits, Billing, Team Members, API Keys.
• Columns (Operations): View (Read), Edit (Update), Create, Delete, Admin.
• Preset Role Bundles: Package standard matrices into pre-configured roles (Owner, Admin, Editor, Viewer) so customers don't have to configure 50 checkboxes manually.

Knowledge Base & FAQs

API Key Generation (Dashboard vs Docs)3

Where and how do I generate API keys for programmatic automation?

Why should secret API keys be generated inside a secure dashboard rather than public documentation?

What is the difference between public client publishable keys and secret backend API keys?

Live vs Test Mode Tokens1

What is the difference between Live Mode (amaris_live_) and Test Mode (amaris_test_) keys?

Bearer Authentication & TLS 1.31

How do I authenticate HTTP REST API requests in cURL, Node.js, and Python?

Scopes & Permission Matrices1

What granular scopes are available for restricting token permissions?

Rate Limits, Quotas & Retry Backoff1

What rate limits are enforced and what headers should developers inspect?

Webhooks & HMAC Verification1

How do Webhooks work and how do I verify HMAC signatures?