Authenticated Settings API

Authenticated Settings API

These routes are served from the installation’s application origin and require Laravel Sanctum authentication.

Tested routes

Method	Path	Result
GET	/api/settings	Collection of general setting resources; 404 when empty
POST	/api/settings	Create settings; returns 201 after validation
GET	/api/settings/{id}	Retrieve one numeric settings ID
PUT, PATCH	/api/settings/{id}	Update one numeric settings ID
DELETE	/api/settings/{id}	Soft-delete one numeric settings ID
GET	/api/settings/current	Current settings for the authenticated context
GET	/api/settings/service	Current semester/year and service-derived settings

The application also contains operator-oriented settings routes. They are not documented here until their authorization, examples, and compatibility contract are covered as a public integration surface.

Read settings

GET /api/settings
Accept: application/json
Authorization: Bearer YOUR_TOKEN

The collection uses KoAkademy’s GeneralSettingResource. Consumers should request only fields they need and must not assume internal configuration or secrets will be returned.

Create settings

POST /api/settings
Accept: application/json
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "site_name": "Example School",
  "site_description": "Student and faculty portal",
  "support_email": "support@example.edu"
}

Successful creation returns HTTP 201:

{
  "message": "General settings created successfully",
  "data": {}
}

data is a general setting resource and can gain fields. A validation failure returns HTTP 422 with an errors object.

Public website settings

GET /api/v1/public/settings does not require authentication, but an administrator must enable both the public API and public-settings feature and choose allowed fields. A successful response has this form:

{
  "message": "Public website settings retrieved successfully",
  "data": {
    "site_name": "Example School",
    "theme_color": "#123456",
    "support_email": "support@example.edu"
  }
}

When disabled it returns HTTP 404 with data: null. Only administrator-selected fields are returned; clients must tolerate fields being absent.

Authorization warning

Settings can contain operational or institution-specific values. Treat token possession as sensitive and apply least privilege. Route authentication does not eliminate the need for operator review of who can issue and use integration tokens.