RLICApi — API Guide

1. Base URL

Use whatever host/port your deployment is running on, for example:

http://<your-server>/api/...

All routes below are relative to that base.

2. Two kinds of endpoints in this API

HTTP Basic authentication has been removed from every endpoint in this API. Everything now runs on a single Bearer-token model, issued by one endpoint (/api/v1/authenticate) that supports two different grant types depending on who's calling:

Both grants are sent to the exact same URL, POST /api/v1/authenticate — see section 3 for the two request bodies. In both cases you get back the same shape of response (access_token/refresh_token/etc.); which grant you used just changes what the token is allowed to do.

Until this change, the business endpoints checked a UserID/Password pair via an HTTP Basic Authorization header on every call, independently of the bearer token layer. That has been retired: any client (including the Android app) still sending a Basic header to a business endpoint will now get HTTP 401 and must switch to the password grant above.

3. Authenticate — get a token

The same endpoint accepts either grant. Send only one pair of fields — whichever matches how you're calling.

Client credentials grant (app-level "client" token — only good for the token-management endpoints, not business data):

POST /api/v1/authenticate
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Password grant (per-user "user" token — required for every business data endpoint in section 11; this replaces HTTP Basic authentication):

POST /api/v1/authenticate
Content-Type: application/json

{
  "userid": "your_business_userid",
  "password": "your_password"
}

Success response (HTTP 200, same shape for both grants):

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "6oX3...",
  "token_type": "Bearer",
  "access_token_expire_in": "10m",
  "refresh_token_expire_in": "1d"
}

• access_token — put this in the Authorization header of every call: Authorization: Bearer <access_token>.
• access_token is short-lived (10 minutes by default). When it expires, use refresh_token to get a new one.
• refresh_token lasts longer (1 day by default). When it also expires, call /authenticate again with the same grant.

Both lifetimes are configurable per deployment and apply to both grants — if your server returns different values than the defaults above, that's expected.

Error responses (still HTTP 200, see section 10 for the error shape):

4. Calling a protected endpoint

Add the access token to every request:

GET /api/v1/health-check
Authorization: Bearer eyJhbGciOi...

If the token is missing, malformed, or expired, you'll get an ApiError with code 401.

Every business data endpoint (section 11) additionally requires the token to be a "user" token from the password grant — a "client" token from the client-credentials grant is rejected with 401 even though it's otherwise valid, because those endpoints need to know which real person is calling.

5. Refresh — get a new access token

POST /api/v1/refresh-token
Authorization: Bearer <access_token>   (can be expired — still required)
Content-Type: application/json

{
  "refresh_token": "6oX3..."
}

Success response:

{
  "access_token": "eyJhbGciOi...(new)",
  "access_token_expire_in": "10m"
}

Error codes: 201 invalid/expired refresh token · 202 unexpected server error.

6. Revoke — log out

POST /api/v1/revoke-token
Authorization: Bearer <access_token>   (can be expired — still required)
Content-Type: application/json

{
  "refresh_token": "6oX3..."
}

Success: {"status": true, "code": 200, "message": "Revoke token with success"}

Error codes: 201 invalid/expired refresh token · 202 unexpected server error.

7. Health check

GET /api/v1/health-check

No authentication required. Returns "Application is running..." with HTTP 200. Use this for uptime monitors — it only confirms the web app is responding, not that the database is reachable.

8. Registering a new client (administrators only)

POST /api/v1/clients
X-Setup-Key: <ClientRegistrationSetupKey from Web.config>
Content-Type: application/json

{
  "client_id": "new_client",
  "client_secret": "a-strong-secret",
  "project_code": "optional"
}

This endpoint is protected by a shared secret header, not a bearer token, since there's no client yet to issue one to. Keep ClientRegistrationSetupKey as secret as a database password.

No clients exist until one is registered here. If Authenticate keeps returning "No client_id found", this step hasn't been done yet — it doesn't use your regular UserID/Password.

Error codes: 401 missing/wrong setup key · 301 missing fields · 303 client already exists · 304 unexpected server error.

9. Test server vs. live server

This API can reach two physically separate SQL Server databases for the same brand: the Live server (real production/customer data) and a separate Test server, set up and maintained by an administrator. Every call this API makes goes to Live unless something below specifically redirects it to Test — most callers never need to think about this at all.

If you're just calling the API normally (your own app, Postman, a script), you don't do anything differently — your traffic goes to Live unless an administrator has specifically routed your account, your brand, or a named feature to Test (see the administrator note below). An administrator can also approve a specific caller to add ?dbmode=test to one request's own URL, routing just that one call to Test without touching anything else that caller sends.

If you're testing from the API Tester page, a separate, hard-coded safety rule sits on top of all of that and cannot be turned off by any administrator setting: calling any of the following from the Tester page always goes to Test, never Live, no matter what is configured anywhere else —

• PolicyOnboard — submitting a new proposal
• PolicyPaymentCheck and PolicyPaymentCancel — premium collection lookups
• Policy and PolicyInfo's "record a premium payment" write (added 2026-10-07) — only the POST that records a payment; the plain policy lookup GET on these same two endpoints is unaffected and keeps reading Live, exactly like every other Business Data lookup
• Client Registration — creating a new client_id/client_secret pair (section 8 above)
• Authenticate's client_id/client_secret grant — so a client you just registered from the Tester can be logged in again from the Tester, without either step ever touching live data

The one deliberate exception: Authenticate's UserID/password grant — the login panel at the top of the Tester page — is not covered by this rule and always checks your real, live staff account. That's intentional: it's what lets you get a genuine user-level token to test the rest of the Business Data endpoints against real data, exactly as a real caller would.

For administrators: the five other, configurable levels of this routing (global default, per-brand-database, per-feature, per-user, and the per-request ?dbmode=test approval list) are managed from the Server Routing console. None of those settings can override the Tester's own hard rule above — it is checked first and wins unconditionally.

10. Error response format

Every bearer-token endpoint returns HTTP 200 for both success and failure — the outcome is in the JSON body:

On failure:

{ "status": false, "code": 201, "message": "No client_id found" }

On success (for endpoints that don't return their own data):

{ "status": true, "code": 200, "message": "Revoke token with success" }

Always check status first, then use code to branch on the specific outcome if needed.

11. Endpoint directory

This list only ever shows the endpoints your account can currently see. An administrator controls this per account from API Visibility — if a business endpoint you expect to use is missing below, ask your administrator to make it visible to your account. (Token/auth endpoints from sections 1–10 above are not repeated here.)

For exact request parameters and response shape on any of these, see the /// <summary> documentation comment above each method in its controller file under Controllers/, or try it directly in the API Tester.

12. Notes for administrators

• All bearer-token settings live in Web.config under <appSettings>: JwtSigningKey, AccessTokenExpireMinutes, RefreshTokenExpireDays, ClientRegistrationSetupKey.
• Token data lives in two tables (tblApiClient, tblApiRefreshToken) in the local Project_APIDB database; they're created automatically on first run. tblApiRefreshToken gained TokenKind/ProjectCode/UserType columns (also auto-created) so it can tell a "client" refresh token from a "user" one.
• HTTP Basic authentication has been removed from every business endpoint. Any caller still sending a Basic Authorization header — including the current Android app — will get HTTP 401 until it's updated to use the password grant in section 3. This was a deliberate, immediate cutover with no transition period.
• Passwords are still validated against the pre-existing storage (plain text in the legacy user_table, a simple bit-rotation scheme in tblUserName) — this migration changed how a caller proves who they are over HTTP, not how credentials are stored. Moving to a modern password hash is a separate, larger change and is not part of this work.
• This API does not itself enforce HTTPS/TLS — that should be configured at the deployment layer (IIS bindings/Web.config). Bearer tokens and passwords sent over plain HTTP are as exposed in transit as the old Basic header was.
• RunningBusinessByCode/RunningBusinessByCodeDetails' separate UserID routing header (see section 11) is a pre-existing gap, unrelated to and unchanged by this migration: it selects a company database/tier but is never itself authenticated. Closing it would mean redesigning how those two endpoints pick a database, which is out of scope here.
• The Client Registration/Authenticate "always use Test" rule described in section 9 requires a Project_APIDB database to actually exist on whatever server TestServerName points at, with the same tblApiClient table structure as Live (this is created automatically the first time it's needed, the same way the live copy was). If that server/database isn't reachable, Client Registration and the client-credential grant of Authenticate will fail with a visible "Contact system administrator!!!" error when called from the Tester page — they do not silently fall back to Live.