Authentication & Gateway¶

How requests are authenticated, scoped to your tenant, and routed.

The Single Front Door¶

All API traffic transits the API gateway (Apigee). The gateway applies policy, enforces tenant-scoped identity, and routes to the appropriate backend. The Workbench uses the same gateway and the same APIs — there is no privileged bypass.

flowchart LR
    A[Your system] -->|HTTPS + token| B[API Gateway]
    B -->|policy + tenant scope| C[Control-plane services]
    C --> D[Your tenant: runtime, evidence, analytics]

Identity & Scope¶

• Requests carry an authorization token; the gateway validates it and attaches tenant scope.
• Every operation is evaluated in the context of your tenant — you cannot read or write another tenant's data.
• Workload identities (not long-lived static keys) are the preferred machine credential.

Base Path & Versioning¶

The northbound surface is versioned under /raas/api/v1/**. Contracts are typed (OpenAPI); breaking changes are versioned, not silently mutated.

Request & Response Conventions¶

• JSON request/response bodies unless an endpoint explicitly handles artifacts.
• Long-running work returns an operation handle rather than blocking — see Errors & Long-Running Operations.
• Validation happens on the way in; nothing reaches your analytical truth without being validated and evidenced.

What This Means For Integration¶

• Treat the gateway as the only entry point; do not attempt to reach backends directly.
• Scope is implicit from your token — you do not pass a tenant id to "select" a tenant.
• Build for asynchrony: assume run-shaped calls return handles you must poll.