Skip to content

API Usage Auth System

Jump to bottom
simitben edited this page Apr 11, 2026 · 4 revisions

Purpose

This page explains how third-party systems should authenticate and perform basic system checks in SimBiz 6 API V3.

Related Auth Design (Planned Hardening)

Base URL

  • https://<host>/api/v3

Endpoint Summary

No. Endpoint Method Purpose Required Permission Scope
1 /api/v3/auth/token POST Get app bearer token (recommended) Not required (client credentials endpoint)
2 /api/v3/health GET Check API service health Not required (health endpoint)

1) Get App Token (Recommended)

Request

POST /api/v3/auth/token

Required Permission Scope

  • Not required (client credentials endpoint)

Body is required (JSON).

Body Parameters:

Field Required Accepted Value / Format Notes
grant_type No client_credentials default client_credentials
client_id Yes non-empty string app client id
client_secret Yes non-empty string app client secret
organization_code No valid organization code required when app has multiple org access and no default org
organization_id No valid organization id alternative to organization_code

Query Parameters

None.

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • access_token, token_type, expires_in, expires_at, app_code, organization_id, organization_code

Example cURL

curl -X POST "https://<host>/api/v3/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<client-id>",
    "client_secret": "<client-secret>",
    "organization_code": "BHH"
  }'

Success Response Example

{
  "status": "OK",
  "data": {
    "access_token": "<token-value>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-04-10 15:10:00",
    "app_code": "EXT_APP",
    "organization_id": "1",
    "organization_code": "BHH"
  },
  "meta": {
    "execute_time_ms": 12,
    "request_time": "2026-04-10 14:10:00",
    "response_time": "2026-04-10 14:10:00"
  }
}

2) Health Check

Request

GET /api/v3/health

Required Permission Scope

  • Not required (health endpoint)

Query Parameters

None.

Response Fields

Field Type Notes
data object/array Endpoint payload. See success response example for exact fields.
meta object Standard metadata including timing fields.
  • name, status, updated

Example cURL

curl -X GET "https://<host>/api/v3/health"

Success Response Example

{
  "status": "OK",
  "data": {
    "name": "SimBiz 6 API V3",
    "status": "UP",
    "updated": ""
  },
  "meta": {
    "execute_time_ms": 2,
    "request_time": "2026-04-10 14:10:00",
    "response_time": "2026-04-10 14:10:00"
  }
}

Authentication Note (For Protected APIs)

Required (V3):

  • Use token from POST /api/v3/auth/token and pass:
  • Authorization: Bearer <access_token>

Clone this wiki locally