Security and Identity

Security architecture starts with identity. Before a service can enforce access, it must know who is calling and under what authority. Carrier supports JWT authentication for protected routes.

JWT Authentication

Authentication blocks are first-class. The booking-service example pulls every value from environment variables — keeping secrets and per-environment configuration out of source — and names the role claim explicitly:

auth jwt StaffAuth {
issuer: env("JWT_ISSUER", "carrier")
audience: env("JWT_AUDIENCE", "carrier-users")
secret: env("JWT_SECRET", "local-dev-secret")
roles_claim: "roles"
}

Architects should treat JWT design as an enterprise-wide concern. Token issuers, signing keys, expiration, audience, issuer validation, role claims, and tenant claims must be consistent across services.

Protected Routes

Routes declare their authentication and role requirements inline. The protect StaffAuth roles [viewer] clause is not a comment — it is a checked, enforced declaration:

route GET "/slots/search" protect StaffAuth roles [viewer] -> SlotListResponse {
query {
q: String?
status: SlotStatus?
page: Int = 1
per_page: Int = 20
}
 
handler {
let actor = auth.current_user()
return AppointmentSlot.search(
q: query.q,
status: query.status,
page: query.page,
per_page: query.per_page
)
}
}

For enterprise review, every route should be classified — public, authenticated, role-restricted, tenant-scoped, administrative, or system-to-system. Carrier's route declarations and manifest metadata help identify which routes are protected and which need further review.

Identity Propagation Across Services

In distributed systems, identity must propagate carefully. A downstream service may need to know whether a request represents an end user, a backend system, or a delegated workflow. Enterprises should define clear standards for service-to-service identity, token exchange, and audit attribution. The key architectural rule is simple: do not lose accountability at service boundaries.