Service tokens (server-to-server)
Service tokens are deployment-managed shared secrets for InBlack-internal service-to-service calls. They are not customer API credentials and cannot be created in the Portal.
External integrations should use API keys or OAuth via ZITADEL.
Wire format
Send the configured token as a bearer credential:
Authorization: Bearer <service-token>The shared Go middleware compares the complete opaque token with the configured value using a constant-time comparison. The source does not define a prefix, length, JWT structure, or other public token format. Treat the value as an opaque secret.
| Condition | Response |
|---|---|
| Receiving service has no token configured | 500 with service token not configured |
Missing Authorization: Bearer ... | 401 with missing bearer token |
| Token does not match | 403 with invalid service token |
| Token matches | Request context is marked service-authenticated |
Tenant context
The shared middleware reads X-Tenant-ID after authenticating the service token. If the header is present, it places that tenant ID in request context. Possessing a service token alone does not select a tenant.
The internal MCP route requires both authentication and tenant context:
POST https://ai-coo.inblack.app/internal/mcpAuthorization: Bearer <service-token>X-Tenant-ID: <tenant-id>Content-Type: application/json
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}/internal/mcp accepts the AI COO Worker’s configured SERVICE_TOKEN or an authenticated principal with the required internal scope. It is a deployed HTTP route; do not assume that its URL alone provides a network security boundary.
Configuration
Environment-variable names are service-specific. Common source-backed names include:
| Variable | Purpose |
|---|---|
SERVICE_TOKEN | General receiving or calling service secret; also used by the AI COO Worker |
PORTAL_API_SERVICE_TOKEN | Token for a service calling Portal API, often with SERVICE_TOKEN as a fallback |
| Service-specific variables | Scoped caller credentials where a service defines them, such as ACCOUNTING_API_SERVICE_TOKEN |
There is no single platform-wide environment-variable catalog or public token registry. Check the caller and receiver configuration before wiring a new internal call.
Security and rotation
- Store service tokens in the deployment secret store and send them only over HTTPS.
- Never expose a token to browser code, logs, documentation examples, or customer configuration.
- Rotate by updating the receiving and calling deployments in a coordinated change.
- Do not assume dual-token overlap: the shared middleware accepts one configured token. A receiver must explicitly implement overlap if a zero-downtime rotation requires it.
- Do not assume service authentication bypasses RBAC, quotas, audit policy, or tenant checks. Those decisions belong to each route after authentication.