API Key Operations Guide - Lynker Spatial

What API Keys Are

Bypass API keys (sk_*) are static secrets injected at the CloudFront edge. When a request arrives from a trusted first-party origin (e.g., hydrofabric.lynker-spatial.com), CloudFront injects the key automatically — no JWT required. For third-party integrations, the key is passed in the X-API-Key header and validated by the Lambda origin.

Keys grant enterprise-level access to all protected tile routes (/api/tiles/{source}/{z}/{x}/{y}) without per-request JWT validation. They are not short-lived and must be rotated manually.

Never embed sk_* keys in public client-side code. Browser apps should either use a server-side proxy that holds the key, or obtain short-lived per-user Cognito tokens for direct tile requests.

Naming Convention

Pattern	Example	Use
`sk_{app}_{random}`	`sk_nymesonet_3f4a2b9c`	Recommended — human-readable prefix + entropy suffix
`sk_{app}`	`sk_nymesonet`	Weak — readable name only, guessable; avoid for production
Random opaque	`f3b2c1d4a5e6f7a8b9c0`	Max security — store friendly name as metadata separately

Use one key per application or integration. Per-app keys make it trivial to revoke one client's access without impacting others and keep audit logs clean.

Provisioning a New Key

Generate a high-entropy key

openssl rand -hex 24 | sed 's/^/sk_nymesonet_/'
# → sk_nymesonet_9a1f2b3c4d5e6f7a8b9c1d2e3f4a5b6c

Store the key in your CI secrets store or AWS Secrets Manager

aws secretsmanager create-secret \
  --name "tiles/bypass-keys/nymesonet" \
  --secret-string "sk_nymesonet_9a1f2b3c4d5e6f7a8b9c1d2e3f4a5b6c"

Add the key to terraform/terraform.tfvars

bypass_api_keys = [
  "sk_hydrofabric_viewer_<existing>",
  "sk_app_demo_<existing>",
  "sk_nymesonet_9a1f2b3c4d5e6f7a8b9c1d2e3f4a5b6c",
]

terraform.tfvars is gitignored. In CI, inject via the TF_VAR_bypass_api_keys environment variable (JSON array string).

Deploy

./scripts/deploy.sh

The deploy script builds the Lambda image and applies Terraform. The CloudFront function and Lambda are updated atomically.

Using a Key (Third-Party Integrations)

Pass the key in the X-API-Key header:

curl -H "X-API-Key: sk_nymesonet_9a1f2b3c4d5e6f7a8b9c1d2e3f4a5b6c" \
  "https://tiles.lynker-spatial.com/api/tiles/lynker-spatial-modeling-fabric/5/9/11" \
  -o tile.pbf

Or in code:

import requests

resp = requests.get(
    "https://tiles.lynker-spatial.com/api/tiles/lynker-spatial-modeling-fabric/5/9/11",
    headers={"X-API-Key": "sk_nymesonet_9a1f2b3c4d5e6f7a8b9c1d2e3f4a5b6c"},
)
resp.raise_for_status()
open("tile.pbf", "wb").write(resp.content)

Key Rotation

Generate a new key with the same naming prefix.
Add it to bypass_api_keys alongside the old key (both active).
Deploy — both keys are now valid.
Update all consumers to use the new key.
After a brief overlap window (24–48 hours), remove the old key from bypass_api_keys.
Deploy again to deactivate the old key.

Blast radius: A single shared key means revoking it affects all clients. Prefer one key per app so rotation is surgical.

Single Key vs. Per-App Keys

	Single key	Per-app keys
Operational overhead	Low	Medium
Blast radius on rotation/revocation	All clients	One client
Audit granularity	None	Per-app
Recommended for	Internal tooling only	All external integrations

Advanced: Per-Key Source Restrictions

By default a bypass key grants access to all tile sources. To restrict a key to specific sources, update the CloudFront viewer-request function (cloudfront_function_forward_host.tf) with a key-to-sources mapping and validate the source path segment against it. Contact the platform team for an implementation example.