How do you enforce a non-human identity when a CI pipeline or an AI service validates JSON payloads?
Organizations increasingly automate data validation as part of build, test, and deployment workflows. The actors behind those automated steps are not people, they are service accounts, build agents, or large language models that need permission to send JSON to a validator. Treating those callers like ordinary users leads to over-privileged tokens, secret leakage, and audit gaps. The challenge is to give a machine identity just enough rights to run a schema check while still keeping an audit record of what was validated.
Understanding non-human identities
A non-human identity is any credential that represents software rather than a person. Typical examples include:
- CI/CD service accounts that run test suites or build commands
- AI assistants that generate JSON configurations for downstream services
- Batch jobs that ingest data feeds and need to verify format before storage
All of these identities are issued by an identity provider (IdP) using OIDC or SAML. The IdP can embed group membership, role tags, or custom claims that describe the purpose of the service account. Those claims become the basis for fine-grained authorization decisions.
Why JSON schema validation needs identity awareness
JSON schema is a powerful way to enforce structure, type constraints, and required fields. However, schema validation alone does not answer two critical questions:
- Who initiated the validation request?
- What should happen if the payload contains sensitive values?
When a human runs a curl request against a validator, the request is naturally tied to a user session that can be logged. With a service account, the request often arrives with a static API key that is shared across many jobs, making it impossible to trace the exact source of a bad payload. Moreover, some schemas allow optional fields that may contain secrets such as API keys or passwords. Without a guardrail that can mask or block those fields, the validator might inadvertently expose them in logs or downstream systems.
Architectural pattern for identity-aware JSON schema validation
The solution separates three responsibilities:
- Setup: Define non-human identities in your IdP, assign them minimal scopes, and configure OIDC or SAML tokens that the CI jobs or AI agents will present.
- The data path: Place a Layer 7 gateway between the caller and the JSON validator. This gateway inspects the HTTP payload, extracts the identity token, and decides whether to allow the request.
- Enforcement outcomes: The gateway can record each validation request, mask any fields marked as sensitive, and require a just-in-time approval step for high-risk payloads.
Only when the gateway sits in the data path can you guarantee that every request, even from a non-human identity, is subject to the same guardrails as a human-initiated request.
Implementing the pattern with hoop.dev
Once the three responsibilities are clear, hoop.dev provides the concrete data-path component that enforces them. Deploy the gateway using the quick-start guide; the gateway runs as a Docker Compose service or in Kubernetes, with an agent colocated near the JSON validator. Register the validator as a connection in hoop.dev, supplying the host, port, and the credential that the gateway will use to talk to the validator. The credential never leaves the gateway, so the service account never sees a secret.
Configure hoop.dev to verify incoming OIDC tokens against your IdP. The token’s claims are mapped to a role that defines which schemas the caller may validate. For example, a "build-agent" role can run only the CI-pipeline schema while an "ai-assistant" role can run a more restrictive configuration-generator schema. hoop.dev then applies the following enforcement outcomes:
- It records each validation request, including the identity, timestamp, and the JSON payload hash, providing an audit trail.
- If the payload contains fields marked as sensitive in the schema (using masking extensions), hoop.dev masks those values before they reach logs or downstream services.
- For high-risk schemas, hoop.dev can pause the request and route it to a human approver, implementing just-in-time access without granting standing permissions.
All of these capabilities are configured through hoop.dev’s declarative policy files; the documentation walks you through adding masking rules, approval workflows, and audit retention settings. Start with the getting-started guide to spin up the gateway, then explore the feature overview for deeper policy examples.
FAQ
Can I use existing service accounts without changing my CI configuration?
Yes. hoop.dev can accept any OIDC token that your IdP issues. You only need to point your CI jobs at the gateway’s endpoint instead of the validator directly. The underlying service account credentials remain unchanged.
What happens to validation logs that contain secrets?
When a schema marks a field as sensitive, hoop.dev masks that field in all logs and audit records. The original value is never stored outside the gateway process.
Do I need to modify my JSON schemas to work with hoop.dev?
No code changes are required. Adding optional masking annotations or defining which schemas each role may access are the only schema-level adjustments, and those are purely declarative.
By treating every automated caller as a non-human identity and routing its traffic through a dedicated gateway, you gain full visibility, control, and protection for JSON schema validation. hoop.dev makes the data-path enforcement straightforward and auditable.
Explore the source code and contribute to the project on GitHub.
