Service Dependencies & Scopes

Scopes control how services access other services' databases and APIs. Every cross-service connection requires a scope grant before the builder will wire it up.

Overview

No unauthenticated cross-service connections. Every dependency goes through an approval gate.

Database Access (Koko Grants)

Services can share database access through Koko's scope system. The owner declares what it shares, a consumer requests access, and an org admin approves.

1. Declare available scopes (owner)

spec:
  scopes:
    - resource: mongodb
      database: shared-data
      allowedConsumers:
        - service: my-consumer
          access: readOnly

Only services listed in allowedConsumers can request access.

2. Request access (consumer)

tawa scopes request --from owner-service --resource mongodb --access readOnly

3. On next deploy

The builder injects a connection string as an environment variable in the consumer service.

Access levels

Environment variables

The owner service name is uppercased with hyphens replaced by underscores:

SHARED_DATA_SVC_MONGODB_URI=mongodb://host:27017/shared-data

Your service's own MONGODB_URI is unaffected — scoped variables always include the owner service name as a prefix.

API Access (Bio-ID Scope Grants)

For service-to-service API calls, use spec.dependencies with Bio-ID scopes:

spec:
  dependencies:
    - service: raterspot
      transport: direct           # injects RATERSPOT_URL
      scopes: [raterspot:rate]   # REQUIRED, cannot be empty

See the catalog-info.yaml reference for full details on the dependencies vs internalDependencies distinction.

Transport Modes

Use direct when you need the URL for direct K8s DNS calls. Use gateway when you need Janus to mediate the request (e.g., for additional gas metering or auth enforcement).

CLI Commands

# Request database access from another service
tawa scopes request --from owner-service --resource mongodb --access readOnly

# List pending and approved scope requests
tawa scopes list

# Approve an incoming scope request (org admin)
tawa scopes approve <request-id>

# Deny an incoming scope request
tawa scopes deny <request-id>

# Revoke previously granted access
tawa scopes revoke <request-id>

Common Patterns

Shared read-only analytics database

# owner-service catalog-info.yaml
spec:
  scopes:
    - resource: mongodb
      database: analytics
      allowedConsumers:
        - service: reporting-service
          access: readOnly

Multi-service event queue sharing

# owner-service catalog-info.yaml
spec:
  scopes:
    - resource: redis
      allowedConsumers:
        - service: worker-service
          access: readWrite