API Reference¶
API Gateway Overview¶
All external API traffic enters through one of four API gateways. Each gateway serves a distinct client type and has its own base URL.
| Gateway | Base URL (Staging) | Client Type |
|---|---|---|
api-gateway-public |
https://[NEEDS TEAM INPUT].stage.orofi.xyz |
Public unauthenticated users |
api-gateway-account |
https://[NEEDS TEAM INPUT].stage.orofi.xyz |
Authenticated account users |
api-gateway-oro |
https://[NEEDS TEAM INPUT].stage.orofi.xyz |
Internal Oro operations |
api-gateway-admin-dashboard |
https://[NEEDS TEAM INPUT].stage.orofi.xyz |
Admin dashboard |
Actual hostnames required
The actual public hostnames for each gateway are not determinable from the infrastructure code alone. [NEEDS TEAM INPUT: provide the specific VirtualService hostname for each gateway.]
Authentication¶
External Client Authentication (JWT)¶
All authenticated API calls require a JWT issued by microservice-identity. The JWT is:
- Signed with the RSA private key from microservice-identity-jwt-private-key-secret
- Validated by the API gateway on each request
- [NEEDS TEAM INPUT: document token expiry, refresh token pattern, and JWT claims structure]
Internal Service Authentication (API Key)¶
Gateways authenticate to downstream microservices using static API keys. Each gateway has its own key:
| Gateway | Key Secret |
|---|---|
api-gateway-public |
{env}-public-gateway-apikey |
api-gateway-account |
{env}-account-gateway-apikey |
api-gateway-oro |
{env}-oro-gateway-apikey |
api-gateway-admin-dashboard |
{env}-admin-dashboard-gateway-apikey |
These keys are passed as HTTP headers (format: [NEEDS TEAM INPUT: header name, e.g., X-API-Key or Authorization: ApiKey {value}]).
mTLS (Internal)¶
All service-to-service communication inside the cluster is protected by Istio mTLS. No additional authentication configuration is needed for inter-service calls — Istio handles it transparently.
API Routes¶
[NEEDS TEAM INPUT: document the actual API routes served by each gateway. The infrastructure code does not contain application-level route definitions — these must be sourced from the microservice repositories. Structure to fill in:]
api-gateway-public Routes¶
| Method | Path | Downstream Service | Auth Required |
|---|---|---|---|
| [NEEDS TEAM INPUT] |
api-gateway-account Routes¶
| Method | Path | Downstream Service | Auth Required |
|---|---|---|---|
| [NEEDS TEAM INPUT] |
api-gateway-oro Routes¶
| Method | Path | Downstream Service | Auth Required |
|---|---|---|---|
| [NEEDS TEAM INPUT] |
api-gateway-admin-dashboard Routes¶
| Method | Path | Downstream Service | Auth Required |
|---|---|---|---|
| [NEEDS TEAM INPUT] |
Rate Limiting¶
[NEEDS TEAM INPUT: document rate limiting configuration — is rate limiting configured at the Istio layer, API gateway level, or not at all?]
Kafka Topics (Event API)¶
Services communicate asynchronously via these Kafka topics:
| Topic | Partitions | Replication | Producers | Consumers |
|---|---|---|---|---|
check-health-topic |
1 | 1 (dev) / 3 (staging) | [NEEDS TEAM INPUT] | [NEEDS TEAM INPUT] |
service-log-topic |
3 | 1 (dev) / 3 (staging) | All services | microservice-analytics |
client-log-topic |
3 | 1 (dev) / 3 (staging) | [NEEDS TEAM INPUT] | microservice-analytics |
account-event-log-topic |
3 | 1 (dev) / 3 (staging) | [NEEDS TEAM INPUT] | microservice-analytics |
Health Check Endpoints¶
All services expose a health check endpoint used by Kubernetes liveness and readiness probes.
| Service | Health Endpoint | Port |
|---|---|---|
| All services | /health (assumed — [NEEDS TEAM INPUT: confirm]) |
80 |