Skip to content

API Reference

The API reference is grouped by business area. It covers the client and operational endpoints provided by sms-router-service and client-service.

Domains and audiences

Domain Audience Authentication Purpose
Messaging External clients Bearer JWT through the gateway Send OTP, transactional, and promotional SMS; check status
Campaigns External clients Bearer JWT through the gateway Create, preview, view, pause, resume, reschedule, cancel, and resend campaigns
Routing configuration Internal operators and automation X-Admin-API-Key Manage MNO/IPTSP groups, credentials, channels, sender routes, fallbacks, and rates
Router operations Platform probes and internal operators Open basic probes; admin key for details Check health, metrics, scheduled tasks, logs, threads, configuration, and migrations
Identity and sessions External clients Login credentials, refresh token, or bearer JWT Log in, refresh tokens, log out, and view the current identity
Client and user administration Internal operators and automation X-Admin-API-Key Manage clients, contact and DLR settings, balance top-ups, users, and allocations
Balance operations Internal platform services X-Admin-API-Key Read billing settings, deduct balances, issue refunds, and reverse deductions
Reporting and export Internal report users and operators X-Admin-API-Key View CDRs, campaigns, dashboards, summaries, and CSV exports
Client runtime operations Platform probes and internal operators Currently open on the direct service port Check client-service health and diagnostics

Each API operation states who can use it:

  • External client endpoints are supported through gateway-service.
  • Internal operator endpoints must stay on a restricted management network and must not be exposed as client self-service.
  • Platform probe endpoints can be called by trusted infrastructure without application credentials.

Authentication and trust

External client routes

Clients send Authorization: Bearer <JWT> to the gateway. The gateway validates the token and session, removes identity headers supplied by the caller, and adds X-Client-Id, X-User-Id, X-Username, and X-Status. The router trusts these gateway headers and does not validate the JWT again.

Do not expose router or client-service ports directly to client networks. A direct router caller could send false identity headers. A direct client-service caller could reach /api/** and actuator endpoints through the current catch-all security configuration.

Operator and internal routes

/admin/**, /internal/**, and restricted actuator endpoints require:

X-Admin-API-Key: <secret>

The admin API key is a sensitive platform secret. Client administration, reporting, routing configuration, and internal balance endpoints use it. Routing responses may contain decrypted aggregator passwords. Do not log the key, admin request headers, or sensitive response bodies.

Operational routes

Only these router endpoints are intentionally open:

  • GET /actuator/health/liveness
  • GET /actuator/health/readiness
  • GET /actuator/info

The main health endpoint requires the admin key because it includes database and scheduler details.

Client-service currently allows direct access to all actuator paths while management.endpoints.web.exposure.include=*. Restrict network access to port 9014 and expose only required actuator endpoints in production.

Error envelopes

Most controller errors use:

{
  "status": 400,
  "error": "validation_failed",
  "message": "request validation failed",
  "details": {
    "optional": "context"
  }
}

Authentication filters run before controllers and return a smaller body:

{ "error": "Missing trusted gateway headers" }

or:

{ "error": "Invalid or missing admin API key" }

Common HTTP errors:

  • 400 for invalid or malformed input;
  • 401 or 403 for authentication, permission, or account-state problems;
  • 402 for balance deduction failures;
  • 404 when a resource is missing or belongs to another client;
  • 409 for state, idempotency, or configuration conflicts;
  • 415 for unsupported content types;
  • 422 when an operator route cannot be found;
  • 502 when a balance or refund dependency fails.

Each domain page lists its errors with examples.

Client-service business errors use a different legacy envelope:

{
  "responseCode": "SK400",
  "responseMessage": "Validation failed",
  "data": { "amount": "must be greater than 0" }
}

Some client-service errors return HTTP 200 with a non-success responseCode. Consumers must check both the HTTP status and responseCode. The client-service admin-key filter returns HTTP 403 without this legacy body.

Idempotency contract

Direct SMS submission and both campaign creation methods accept an optional Idempotency-Key header.

  • A key belongs to one authenticated username.
  • The router keeps it for 24 hours.
  • The router reserves it before changing the balance.
  • Retrying the same completed request returns the original response without another charge.
  • Reusing the key with different input returns 409 idempotency_mismatch.
  • Retrying while the first request is still running returns 409 idempotency_in_progress with Retry-After: 2.
  • A failed request releases the key so it can be retried.
  • For CSV campaigns, the comparison includes the request details and CSV file bytes.

Use a stable ID for the business operation. Do not reuse a key for a different message or campaign.