canonical: https://jentic.com/apis/googleapis.com/servicecontrol # Google Service Control API Service Control is the runtime admission-control and telemetry-reporting endpoint for services integrated with Google's Service Infrastructure. Service producers call check before serving a request to enforce per-consumer policy, allocateQuota to debit metered quota buckets, and report to push usage and audit telemetry into the GCP control plane. It is what powers the per-consumer enforcement and billing for Google's own and partner-managed APIs. ## For AI agents Run admission checks, allocate quota, and report usage telemetry for services built on Google's Service Infrastructure. ## Scope Does not handle end-user authentication, service definition publishing, or general logs ingestion - use for runtime admission control, quota allocation, and telemetry reporting only. ## Capabilities - Run a pre-request check to validate that the consumer has the service enabled and is within policy - Allocate quota against per-consumer metric buckets before serving an operation - Report telemetry - operation name, consumer, labels, metric values - for billing and audit - Batch multiple operations into a single report call to reduce overhead - Surface check errors (SERVICE_NOT_ACTIVATED, BILLING_DISABLED, RESOURCE_EXHAUSTED) for clear caller feedback ## Use cases ### Managed Service Admission Control Producers running a managed service on GCP call services.check before each request to confirm the consumer project has the service enabled, billing is healthy, and the call is policy-compliant. This replaces hand-rolled IAM and billing checks with the same control plane Google's own services use, returning structured errors that map cleanly to HTTP status codes. Example prompt: Call POST /v1/services/{serviceName}:check with the consumer project id and operation name; deny the inbound request if the response contains a checkError. ### Metered Quota Enforcement For metered or rate-limited operations, call services.allocateQuota with the metric and quantity before processing the request, then services.report after to confirm the allocation was used. Service Control handles per-consumer counters across regions and exposes RESOURCE_EXHAUSTED when the consumer hits their limit. Example prompt: Call POST /v1/services/{serviceName}:allocateQuota with quotaMetrics including 'reads/min' set to 1 for the consumer, then proceed only if the response has no allocationErrors. ### Usage and Audit Telemetry Reporting After serving each request, call services.report with operation metadata so billing, audit logs, and SLO reporting see the call. The report endpoint accepts batches of operations with metric values and labels, and integrates with Cloud Billing and Cloud Audit Logs without additional plumbing. Example prompt: Buffer up to 1,000 operations, then call POST /v1/services/{serviceName}:report with the batch and a unique operationId per entry. ### AI Agent Service Operator An AI agent that fronts a managed-service request handler uses Service Control to enforce policy and emit telemetry without each request handler having to embed the logic. Through Jentic the agent invokes check, allocateQuota, and report as discrete operations and never touches the producer's service account credentials directly. Example prompt: On each inbound request, call services:check, then allocateQuota, run the underlying business logic, and finally call services:report with the captured metric values. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v1/services/{serviceName}:check | Run a pre-request admission check | | POST | /v1/services/{serviceName}:allocateQuota | Allocate quota against per-consumer metrics | | POST | /v1/services/{serviceName}:report | Report usage and audit telemetry | ## Key resources - **services** — Run check, allocateQuota, and report against a managed service - **operations** — Operation definitions used in check and report payloads ## Why Jentic - **Setup:** Wiring Google Service Control by hand means configuring a producer service account, minting OAuth access tokens against servicecontrol.googleapis.com, and refreshing them yourself. Through Jentic you install once, import the Service Control API from the API Directory, store the OAuth credential once, and your agent calls it. - **Permission scoping:** Service Control puts the service name in the URL path (/v1/services/{serviceName}:check), so a rule can pin your agent to one service: it can run admission checks for that service and nothing else. You choose the operations it may call, so allocateQuota and report are not included unless you add them. - **Credential handling:** Your Service Control OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'check whether a consumer can call my service' or 'report service usage', and Jentic returns the matching Service Control operation with its consumer and operation schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Google Service Management API** — Producers register and manage service configurations; Service Control then enforces them at runtime. - **Google Service Usage API** — Enables or disables a service on a consumer project, which Service Control then enforces. - **Google Cloud Logging API** — Holds the audit logs that Service Control report telemetry feeds into. - **Google Cloud Monitoring API** — Direct metric ingestion alternative when you do not need the per-consumer admission semantics of Service Control. ## FAQ ### What authentication does the Service Control API use? Service Control uses OAuth 2.0 with the cloud-platform or servicecontrol scope, called by the producer's service account that holds roles/servicemanagement.serviceController. Through Jentic the credentials are stored encrypted in your Jentic One instance and exchanged for a scoped token at execution. ### Does the Service Control API perform IAM authorization for end users? No. services:check validates service activation, billing, and policy at the consumer-project level, not end-user IAM. End-user authorization should be enforced separately in the producer service before the call. ### What are the rate limits for the Service Control API? Google enforces high per-service quotas (tens of thousands of QPS) for check and report because they are designed to sit on the request hot path. Practical limits depend on the consumer project and are surfaced as RESOURCE_EXHAUSTED in checkErrors. ### How do I report telemetry through Jentic? Run the Jentic search query 'report telemetry to service control', load POST /v1/services/{serviceName}:report, and execute it with a list of Operation objects. Jentic handles the producer service account token so the agent only constructs the operation payloads. ### Why does check sometimes return success with checkErrors populated? Check returns a 200 with structured checkErrors so the caller can decide whether to deny the request, surface a billing-disabled message, or fall back. Only treat the response as 'allowed' when checkErrors is empty. ### Can I use the v2 Service Control endpoints? Yes - a v2 surface exists for newer integrations. This enrichment covers v1, which is still the default for most producer integrations and exposes the check, allocateQuota, and report operations directly. ### Can I limit what my agent is allowed to do with the Service Control API? Yes. Because Service Control puts the service name in the URL path, like /v1/services/{serviceName}:check, a rule in your self-hosted Jentic One instance can pin your agent to a single service and let it run admission checks for that service only. You decide which operations the agent may call, so allocateQuota and report stay off the table unless you explicitly add them. The OAuth credential is held encrypted by your own instance and injected at execution, never entering the agent's prompt or logs, so the operator sets exactly what the agent can reach.