Skip to Content
We are live but in Staging 🎉
API ReferenceTransport, Auth, and Conventions

Transport, Auth, and Conventions

Last validated: 2026-05-20

Transport Model

Ignite is gRPC-first at runtime.

Primary gRPC listeners:

  • Compute/Build/Model/Secret: IGNITE_API_LISTEN_ADDR (default 0.0.0.0:50051)
  • AdminService: IGNITE_ADMIN_LISTEN_ADDR (default 0.0.0.0:50052)

Proto HTTP annotations describe gateway/API contracts and REST mapping, but should be treated as contract shape rather than proof that a direct HTTP business endpoint is served by the API binary itself.

Auth Model

Public services use bearer auth and org-aware scope checks.

High-level pattern:

  1. Caller presents bearer token.
  2. Gateway/runtime resolves org identity metadata.
  3. Method scope checks apply (DeployApp, InvokeApp, GetExecution, etc.).

AdminService is internal and mTLS-only by design.

Identifier and Field Conventions

  • App identity uses {organization_name}/{app_name} in API paths and organization_name + app_name in request messages.
  • CLI shorthand commonly uses org:name and resolves missing org from config.
  • Most timestamps are int64 Unix milliseconds.
  • Pagination shape commonly uses limit + cursor + next_cursor.

Shared Enum Families

From ignite_common.proto, common enums include:

  • Runtime and compilation targets (PythonRuntime, RustRuntime, GoRuntime, DenoRuntime)
  • Resource and scaling (ResourceTier, ScaleMetric, ScalingConfig)
  • Lifecycle (DeploymentState, VersionStatus, ExecutionStatus)

Streaming Conventions

Representative streaming APIs:

  • ComputeService.Invoke (server-streaming frames)
  • ComputeService.WatchExecution (state and output progression)
  • BuildService.StreamBuildLogs
  • ModelService.StreamChatCompletion, StreamRerank, StreamInfer

Invoke framing semantics:

  • First frame: response head (status/headers/execution context)
  • Middle frames: zero or more body chunks
  • Final frame: trailer/terminal metadata

Error and Compatibility Guidance

  1. Treat deprecated RPCs as compatibility paths (for example InvokeAsync) and prefer current flow (Invoke).
  2. Service availability can depend on successful startup initialization of required infra (for example build infra initialization for BuildService).
  3. API contract changes should be validated against both proto and service registration wiring in crates/ignite-api/src/lib.rs.

Suggested Direct-Call Baseline

For direct gRPC inspection and troubleshooting:

  • Use grpc reflection where enabled.
  • Verify auth metadata and org context are being passed as expected.
  • Start with health and simple get/list calls before invoking streaming/long-running methods.

gRPC Examples

Health check

grpcurl \
	-H "authorization: Bearer $TOKEN" \
	-d '{}' \
	rpc.dev.dodil.io:443 dodil.ignite.v1.ComputeService/HealthCheck

Get execution by ID

grpcurl \
	-H "authorization: Bearer $TOKEN" \
	-d '{"execution_id":"<execution_id>"}' \
	rpc.dev.dodil.io:443 dodil.ignite.v1.ComputeService/GetExecution

HTTP Examples (Gateway/Annotation Contract)

Create app

curl -sS -X POST \
	-H "Authorization: Bearer $TOKEN" \
	-H "Content-Type: application/json" \
	"https://api.dev.dodil.io/v1/ignite/app/myorg" \
	-d '{
		"organization_name":"myorg",
		"name":"hello-http",
		"resource_tier":"RESOURCE_TIER_SMALL",
		"description":"hello app"
	}'

Get execution by ID

curl -sS \
	-H "Authorization: Bearer $TOKEN" \
	"https://api.dev.dodil.io/v1/ignite/executions/<execution_id>"

App-Specific HTTP URL Invocation

In addition to annotation-mapped API routes, gateway supports host-based app invocation URLs.

Canonical URL format from runtime code paths (FunctionId::to_dns_label + gateway host parser):

  1. Default app port 80: https://<app_name>-<org>.<base_domain>/<path>
  2. Non-default app port: https://<app_name>-<org>-<port>.<base_domain>/<path>

base_domain defaults to ignite.dodil.cloud and is configurable via IGNITE__DNS_TLS__BASE_DOMAIN.

Example:

curl -sS -X POST \
	-H "Authorization: Bearer $TOKEN" \
	-H "Content-Type: application/json" \
	"https://warehouse-query-public.ignite.dodil.cloud/query" \
	-d '{"sql":"select 1"}'

Auth and routing notes:

  1. Gateway enforces bearer auth on host-based invocation.
  2. Caller org must match URL org, except public/* apps which allow authenticated cross-org invoke.
  3. Path and query are forwarded to app service as-is.
  4. Function names with . are encoded as -dot- in host labels.

Bytes and Streaming Practical Notes

  1. For gRPC JSON input, bytes fields are base64-encoded (for example body, source_code, archive).
  2. ComputeService.Invoke is server-streaming and emits head/chunk/trailer frames.
  3. WatchExecution and log stream endpoints should be preferred over polling for long-running tasks.
Ignite API ReferenceComputeService