Cloudflare.ApiShield reference

Configuration

Source: src/Cloudflare/ApiShield/Configuration.ts

The API Shield configuration of a Cloudflare zone — the session identifiers (“auth ID characteristics”) used to attribute API traffic to individual consumers for API Discovery and volumetric abuse detection.

The configuration is a zone singleton: it always exists (defaulting to an empty list), so this resource never creates or deletes anything physical. Reconcile PUTs the configuration when the observed characteristics differ from the desired ones; destroy restores the characteristics the zone had before Alchemy first managed them.

Requires an API Shield entitlement (Enterprise) — on other plans every operation fails with Cloudflare’s NotEntitled error (code 10403).

Configuration: Configuring session identifiers

Identify sessions by an Authorization header

yield* Cloudflare.ApiShield.Configuration("SessionIds", {
  zoneId: zone.zoneId,
  authIdCharacteristics: [{ name: "authorization", type: "header" }],
});

Identify sessions by a cookie and a JWT claim

yield* Cloudflare.ApiShield.Configuration("SessionIds", {
  zoneId: zone.zoneId,
  authIdCharacteristics: [
    { name: "session_id", type: "cookie" },
    { name: '$.cf.token_configurations[?(@.title=="api")].sub', type: "jwt" },
  ],
});

Label

Source: src/Cloudflare/ApiShield/Label.ts

A Cloudflare API Shield user label — a zone-scoped tag that can be attached to registered API operations to organize and filter them (e.g. by team, service, or sensitivity).

The label’s name is its identity (and Cloudflare limits it to 24 characters), so renaming triggers a replacement; only the description is mutable in place. Deleting a label detaches it from any operations server-side.

Label: Creating a Label

Label with a generated name

const label = yield* Cloudflare.ApiShield.Label("TeamPayments", {
  zoneId: zone.zoneId,
  description: "endpoints owned by the payments team",
});

Label with an explicit name

yield* Cloudflare.ApiShield.Label("Pii", {
  zoneId: zone.zoneId,
  name: "pii",
  description: "endpoints that return personal data",
});

Operation

Source: src/Cloudflare/ApiShield/Operation.ts

A Cloudflare API Shield operation — a registered API endpoint on a zone, identified by the (method, host, endpoint) tuple. Registered operations are the unit other API Shield features (schema validation, rate limiting recommendations, API Discovery) attach to.

An operation is pure identity: there is no update API, so changing any property triggers a replacement. Cloudflare upserts by identity — creating an already-registered tuple returns the existing operation — which makes reconciliation race-free.

Endpoint paths may contain {placeholder} templates; Cloudflare normalizes the variable names left-to-right to {var1}, {var2}, … and the normalized form is what is stored and diffed.

Operation: Registering an Operation

Register a GET endpoint

const op = yield* Cloudflare.ApiShield.Operation("GetUser", {
  zoneId: zone.zoneId,
  method: "GET",
  host: "api.example.com",
  endpoint: "/api/v1/users/{id}",
});
// op.endpoint === "/api/v1/users/{var1}"

Register a POST endpoint

yield* Cloudflare.ApiShield.Operation("CreateUser", {
  zoneId: zone.zoneId,
  method: "POST",
  host: "api.example.com",
  endpoint: "/api/v1/users",
});

UserSchema

Source: src/Cloudflare/ApiShield/UserSchema.ts

A Cloudflare API Shield user schema — an OpenAPI v3 document uploaded to a zone for (legacy “classic”) schema validation of API traffic.

An uploaded schema’s contents cannot be modified, so changing the schema source (or the name) triggers a replacement. The only in-place update is enabling validation; Cloudflare forbids disabling an enabled schema, so turning validation back off also triggers a replacement.

For current zone-level schema validation (v2), prefer the Cloudflare.SchemaValidation resources.

UserSchema: Uploading a Schema

Upload an OpenAPI v3 schema

const fs = yield* FileSystem.FileSystem;
const source = yield* fs.readFileString("./openapi.json");

const schema = yield* Cloudflare.ApiShield.UserSchema("PetstoreSchema", {
  zoneId: zone.zoneId,
  name: "petstore",
  schema: source,
});
// schema.schemaId is the Cloudflare-assigned UUID

Upload and enable validation

yield* Cloudflare.ApiShield.UserSchema("PetstoreSchema", {
  zoneId: zone.zoneId,
  schema: source,
  validationEnabled: true,
});