Auth Endpoint Spec

Purpose

Define API V3 auth endpoints for App registration, token issuance, permission inspection, secret rotation, and access control administration.

Scope Status

• This page is a target endpoint spec for the new App-based auth module.
• Core endpoints listed below are implemented in current backend module.

Endpoint Groups

• Public App Authentication
• Authenticated App Introspection
• Admin App Management

Public App Authentication

1) POST /api/v3/auth/token

• Purpose: issue access token using app credentials.
• Auth: no bearer token required.

Request body:

Field	Type	Required	Notes
grant_type	string	No	default client_credentials
client_id	string	Yes	app client id
client_secret	string	Yes	app secret
organization_code	string	No	required if app has multiple orgs and no default org
organization_id	string	No	alternative to organization_code

Response fields:

Field	Type	Notes
access_token	string	opaque bearer token
token_type	string	Bearer
expires_in	int	seconds
expires_at	datetime	YYYY-MM-DD HH:MM:SS
app_code	string	app code
organization_id	string	effective org id
organization_code	string	effective org code

Permission behavior:

• App status must be ACTIVE.
• Secret must be ACTIVE or GRACE and within validity.
• Requested organization must be assigned to app.

---

2) POST /api/v3/auth/token/revoke

• Purpose: revoke current token.
• Auth: bearer token required.

Request body:

Field	Type	Required	Notes
reason	string	No	revoke reason for audit

Response fields:

Field	Type	Notes
revoked	boolean	revoke operation result
token_id	string	internal token id
updated	datetime	response updated timestamp

Permission behavior:

• Any authenticated app can revoke its own token.

Authenticated App Introspection

3) GET /api/v3/auth/me

• Purpose: return current app profile and token context.
• Auth: bearer token required.

Query parameters: none.

Response fields:

Field	Type	Notes
app_id	string	internal app id
app_code	string	app code
app_name	string	app name
status	string	app status
token_id	string	current token id
token_expires_at	datetime	expiry
organizations[]	array	allowed organizations
permissions[]	array	granted permission codes

4) GET /api/v3/auth/me/permissions

• Purpose: return granted permissions for current app.
• Auth: bearer token required.

Query parameters: none.

Response fields:

Field	Type	Notes
app_code	string	app code
permissions[]	array	permission_code, module_code, resource_code, action_code

5) GET /api/v3/auth/me/organizations

• Purpose: return allowed organizations for current app.
• Auth: bearer token required.

Response fields:

Field	Type	Notes
app_code	string	app code
organizations[]	array	organization_id, organization_code, is_default

Admin App Management

Admin endpoints should be protected by internal administrative auth (existing SimBiz admin auth or dedicated auth-admin.* permissions).

6) POST /api/v3/auth/apps

• Purpose: register new app and issue initial secret.

Request body:

Field	Type	Required	Notes
app_code	string	Yes	unique code
app_name	string	Yes	display name
description	string	No	optional
default_organization_id	string	No	optional
organizations[]	array	Yes	initial allowed org list
permissions[]	array	Yes	initial permission codes

Response fields:

Field	Type	Notes
app_id	string	created app id
client_id	string	generated client id
client_secret	string	show once only
secret_version	int	initial version

7) GET /api/v3/auth/apps

• Purpose: list registered apps.

Query parameters:

Field	Type	Required	Notes
status	string	No	filter by ACTIVE/SUSPENDED/REVOKED
q	string	No	search by app code/name

8) GET /api/v3/auth/apps/{app_id}

• Purpose: app detail with org and permission summary.

9) PATCH /api/v3/auth/apps/{app_id}

• Purpose: update app metadata and status-safe fields (not secret).

10) POST /api/v3/auth/apps/{app_id}/rotate-secret

• Purpose: rotate app secret.

Request body:

Field	Type	Required	Notes
grace_hours	int	No	default from config
revoke_existing_tokens	boolean	No	revoke active tokens immediately
reason	string	No	audit reason

Response fields:

Field	Type	Notes
client_secret	string	new secret, show once
secret_version	int	new version
grace_until	datetime	old secret grace cutoff

11) POST /api/v3/auth/apps/{app_id}/suspend

• Purpose: suspend app access immediately.

12) POST /api/v3/auth/apps/{app_id}/reactivate

• Purpose: reactivate app.

13) POST /api/v3/auth/apps/{app_id}/revoke

• Purpose: permanently revoke app and active tokens.

14) PUT /api/v3/auth/apps/{app_id}/permissions

• Purpose: replace permission grants for app.

Request body:

Field	Type	Required	Notes
permissions[]	array	Yes	permission codes

15) PUT /api/v3/auth/apps/{app_id}/organizations

• Purpose: replace allowed organizations for app.

Request body:

Field	Type	Required	Notes
organizations[]	array	Yes	org id/code entries
default_organization_id	string	No	default org

16) GET /api/v3/auth/apps/{app_id}/audit-logs

• Purpose: review auth-related audit trail for one app.

Query parameters:

Field	Type	Required	Notes
event_type	string	No	filter by event
date_from	datetime	No	range start
date_to	datetime	No	range end
page	int	No	pagination
per_page	int	No	pagination

17) GET /api/v3/auth/permissions

• Purpose: list available permission catalog for admin assignment UI.
• Auth: admin user token required.

Query parameters:

Field	Type	Required	Notes
module_code	string	No	filter by module
q	string	No	search by code/resource/action/description

Response fields:

Field	Type	Notes
permission_id	string	internal id
permission_code	string	unique permission code
module_code	string	module group
resource_code	string	resource group
action_code	string	action
description	string	description

18) GET /api/v3/auth/organizations

• Purpose: list active organizations for admin app-org assignment UI.
• Auth: admin user token required.

Query parameters:

Field	Type	Required	Notes
q	string	No	search by id/code/name
page	int	No	default 1
per_page	int	No	default 50, max 200

Response fields:

Field	Type	Notes
organization_id	string	org id
organization_code	string	org code
organization_name	string	org name
isactive	string/int	active flag

Error Codes (Suggested)

Code	Meaning
V3_AUTH_MISSING_CREDENTIAL	missing token or credential
V3_AUTH_INVALID_CLIENT	invalid client_id/client_secret
V3_AUTH_APP_SUSPENDED	app suspended
V3_AUTH_APP_REVOKED	app revoked
V3_AUTH_SECRET_EXPIRED	secret expired or revoked
V3_AUTH_PERMISSION_DENIED	app lacks required permission
V3_AUTH_ORG_DENIED	app not allowed for requested org
V3_AUTH_TOKEN_EXPIRED	token expired
V3_AUTH_TOKEN_REVOKED	token revoked

Notes

• V3 token issuance endpoint is POST /api/v3/auth/token.
• All auth responses should keep standard V3 envelope (status, data, meta).
• App-token permission checks are enforced per-route when a matching active record exists in system_api3_route_permission.