Authentication and scopes

Every public API request uses a scoped live or sandbox key.

Create API keys on /developer — the plaintext is shown once, only a SHA-256 hash is stored, and revocation is immediate. Pass the key either way:

Generated contract: download the versioned OpenAPI 3.1 JSON for client generation, route scopes, canonical opportunity fields, error envelopes, pagination, and rate-limit headers.

bash

# Preferred
curl -H "Authorization: Bearer wl_live_..." \
  https://api.winlayer.ai/api/v1/public/opportunities

# Also accepted
curl -H "x-api-key: wl_live_..." \
  https://api.winlayer.ai/api/v1/public/opportunities

Environments

wl_live_... keys resolve the workspace that created them. wl_test_... keys are isolated from production data and return deterministic synthetic fixtures for every read-only public resource.

Scopes

text

workspace:read       Verify the key and workspace
opportunities:read  List and inspect scored opportunities
signals:read        Read normalized source signals and provenance
forecasts:read      Read published acquisition and recompete forecasts
contacts:read       Read tenant-owned relationship contacts
agencies:read       Read canonical federal agency entities
relationships:read Read accepted procurement-graph relationships
intelligence:read  Read published, governed intelligence objects
pipeline:read       Read tracked pipeline state
agents:read         Read the agent catalog and generated outputs
agents:run          Run grounded AI agents (live keys only)
actions:write       Approve or reject proposed actions (live keys only)
usage:read          Read metered AI usage

Endpoints reject missing scopes with 403. Sandbox keys cannot include live-only scopes.

Versioning and deprecation

The major version is part of every URL: /api/v1. WinLayer may add optional fields inside a major version, but does not remove fields, rename fields, or change their meaning without a new major version. A retired route receives at least 180 days of notice in the changelog and response headers before removal. Consumers should ignore unknown fields and follow opaque pagination cursors instead of constructing them.

Rotating a key: create a new API key, switch your integration, then revoke the old — the audit trail keeps the key's history. See rate limits before you deploy a poller.