santhoshj/headroom
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): generate auth docs and archive p00 change

Browse Source
This commit is contained in:
Santhosh Janardhanan
2026-02-18 14:26:51 -05:00
parent 032da7c40c
commit cdfb15bbfd
21 changed files with 3214 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

668
backend/resources/views/scribe/index.blade.php Normal file
View File

@@ -0,0 +1,668 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
<title>Headroom API</title>
<link href="https://fonts.googleapis.com/css?family=Open+Sans&display=swap" rel="stylesheet">
<link rel="stylesheet" href="{{ asset("/vendor/scribe/css/theme-default.style.css") }}" media="screen">
<link rel="stylesheet" href="{{ asset("/vendor/scribe/css/theme-default.print.css") }}" media="print">
<script src="https://cdn.jsdelivr.net/npm/lodash@4.17.10/lodash.min.js"></script>
<link rel="stylesheet"
href="https://unpkg.com/@highlightjs/cdn-assets@11.6.0/styles/obsidian.min.css">
<script src="https://unpkg.com/@highlightjs/cdn-assets@11.6.0/highlight.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jets/0.14.1/jets.min.js"></script>
<style id="language-style">
/* starts out as display none and is replaced with js later */
body .content .bash-example code { display: none; }
body .content .javascript-example code { display: none; }
</style>
<script>
var tryItOutBaseUrl = "http://localhost/api";
var useCsrf = Boolean();
var csrfUrl = "/sanctum/csrf-cookie";
</script>
<script src="{{ asset("/vendor/scribe/js/tryitout-5.7.0.js") }}"></script>
<script src="{{ asset("/vendor/scribe/js/theme-default-5.7.0.js") }}"></script>
</head>
<body data-languages="[&quot;bash&quot;,&quot;javascript&quot;]">
<a href="#" id="nav-button">
<span>
MENU
<img src="{{ asset("/vendor/scribe/images/navbar.png") }}" alt="navbar-image"/>
</span>
</a>
<div class="tocify-wrapper">
<div class="lang-selector">
<button type="button" class="lang-button" data-language-name="bash">bash</button>
<button type="button" class="lang-button" data-language-name="javascript">javascript</button>
</div>
<div class="search">
<input type="text" class="search" id="input-search" placeholder="Search">
</div>
<div id="toc">
<ul id="tocify-header-introduction" class="tocify-header">
<li class="tocify-item level-1" data-unique="introduction">
<a href="#introduction">Introduction</a>
</li>
</ul>
<ul id="tocify-header-authenticating-requests" class="tocify-header">
<li class="tocify-item level-1" data-unique="authenticating-requests">
<a href="#authenticating-requests">Authenticating requests</a>
</li>
</ul>
<ul id="tocify-header-authentication" class="tocify-header">
<li class="tocify-item level-1" data-unique="authentication">
<a href="#authentication">Authentication</a>
</li>
<ul id="tocify-subheader-authentication" class="tocify-subheader">
<li class="tocify-item level-2" data-unique="authentication-POSTapi-auth-login">
<a href="#authentication-POSTapi-auth-login">Login and get tokens</a>
</li>
<li class="tocify-item level-2" data-unique="authentication-POSTapi-auth-refresh">
<a href="#authentication-POSTapi-auth-refresh">Refresh access token</a>
</li>
<li class="tocify-item level-2" data-unique="authentication-POSTapi-auth-logout">
<a href="#authentication-POSTapi-auth-logout">Logout current session</a>
</li>
</ul>
</ul>
</div>
<ul class="toc-footer" id="toc-footer">
<li style="padding-bottom: 5px;"><a href="{{ route("scribe.postman") }}">View Postman collection</a></li>
<li style="padding-bottom: 5px;"><a href="{{ route("scribe.openapi") }}">View OpenAPI spec</a></li>
<li><a href="http://github.com/knuckleswtf/scribe">Documentation powered by Scribe ✍</a></li>
</ul>
<ul class="toc-footer" id="last-updated">
<li>Last updated: February 18, 2026</li>
</ul>
</div>
<div class="page-wrapper">
<div class="dark-box"></div>
<div class="content">
<h1 id="introduction">Introduction</h1>
<p>Resource planning and capacity management API</p>
<aside>
<strong>Base URL</strong>: <code>http://localhost/api</code>
</aside>
<pre><code>Authenticate by sending `Authorization: Bearer {access_token}` on protected endpoints.
Access tokens are valid for 60 minutes. Use `/api/auth/refresh` with your refresh token to obtain a new access token and refresh token pair.</code></pre>
<h1 id="authenticating-requests">Authenticating requests</h1>
<p>To authenticate requests, include an <strong><code>Authorization</code></strong> header with the value <strong><code>"Bearer Bearer {token}"</code></strong>.</p>
<p>All authenticated endpoints are marked with a <code>requires authentication</code> badge in the documentation below.</p>
<p>Get tokens from <code>POST /api/auth/login</code>, send access token as <code>Bearer {token}</code>, and renew with <code>POST /api/auth/refresh</code> before access token expiry.</p>
<h1 id="authentication">Authentication</h1>
<p>Endpoints for JWT authentication and session lifecycle.</p>
<h2 id="authentication-POSTapi-auth-login">Login and get tokens</h2>
<p>
<small class="badge badge-darkred">requires authentication</small>
</p>
<p>Authenticate with email and password to receive an access token and refresh token.</p>
<span id="example-requests-POSTapi-auth-login">
<blockquote>Example request:</blockquote>
<div class="bash-example">
<pre><code class="language-bash">curl --request POST \
"http://localhost/api/api/auth/login" \
--header "Authorization: Bearer Bearer {token}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"email\": \"user@example.com\",
\"password\": \"secret123\"
}"
</code></pre></div>
<div class="javascript-example">
<pre><code class="language-javascript">const url = new URL(
"http://localhost/api/api/auth/login"
);
const headers = {
"Authorization": "Bearer Bearer {token}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"email": "user@example.com",
"password": "secret123"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response =&gt; response.json());</code></pre></div>
</span>
<span id="example-responses-POSTapi-auth-login">
<blockquote>
<p>Example response (200):</p>
</blockquote>
<pre>
<code class="language-json" style="max-height: 300px;">{
&quot;access_token&quot;: &quot;eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...&quot;,
&quot;refresh_token&quot;: &quot;abc123def456&quot;,
&quot;token_type&quot;: &quot;bearer&quot;,
&quot;expires_in&quot;: 3600,
&quot;user&quot;: {
&quot;id&quot;: &quot;550e8400-e29b-41d4-a716-446655440000&quot;,
&quot;name&quot;: &quot;Alice Johnson&quot;,
&quot;email&quot;: &quot;user@example.com&quot;,
&quot;role&quot;: &quot;manager&quot;
}
}</code>
</pre>
<blockquote>
<p>Example response (401):</p>
</blockquote>
<pre>
<code class="language-json" style="max-height: 300px;">{
&quot;message&quot;: &quot;Invalid credentials&quot;
}</code>
</pre>
<blockquote>
<p>Example response (403):</p>
</blockquote>
<pre>
<code class="language-json" style="max-height: 300px;">{
&quot;message&quot;: &quot;Account is inactive&quot;
}</code>
</pre>
<blockquote>
<p>Example response (422):</p>
</blockquote>
<pre>
<code class="language-json" style="max-height: 300px;">{
&quot;errors&quot;: {
&quot;email&quot;: [
&quot;The email field is required.&quot;
],
&quot;password&quot;: [
&quot;The password field is required.&quot;
]
}
}</code>
</pre>
</span>
<span id="execution-results-POSTapi-auth-login" hidden>
<blockquote>Received response<span
id="execution-response-status-POSTapi-auth-login"></span>:
</blockquote>
<pre class="json"><code id="execution-response-content-POSTapi-auth-login"
data-empty-response-text="<Empty response>" style="max-height: 400px;"></code></pre>
</span>
<span id="execution-error-POSTapi-auth-login" hidden>
<blockquote>Request failed with error:</blockquote>
<pre><code id="execution-error-message-POSTapi-auth-login">
Tip: Check that you&#039;re properly connected to the network.
If you&#039;re a maintainer of ths API, verify that your API is running and you&#039;ve enabled CORS.
You can check the Dev Tools console for debugging information.</code></pre>
</span>
<form id="form-POSTapi-auth-login" data-method="POST"
data-path="api/auth/login"
data-authed="1"
data-hasfiles="0"
data-isarraybody="0"
autocomplete="off"
onsubmit="event.preventDefault(); executeTryOut('POSTapi-auth-login', this);">
<h3>
Request&nbsp;&nbsp;&nbsp;
<button type="button"
style="background-color: #8fbcd4; padding: 5px 10px; border-radius: 5px; border-width: thin;"
id="btn-tryout-POSTapi-auth-login"
onclick="tryItOut('POSTapi-auth-login');">Try it out ⚡
</button>
<button type="button"
style="background-color: #c97a7e; padding: 5px 10px; border-radius: 5px; border-width: thin;"
id="btn-canceltryout-POSTapi-auth-login"
onclick="cancelTryOut('POSTapi-auth-login');" hidden>Cancel 🛑
</button>&nbsp;&nbsp;
<button type="submit"
style="background-color: #6ac174; padding: 5px 10px; border-radius: 5px; border-width: thin;"
id="btn-executetryout-POSTapi-auth-login"
data-initial-text="Send Request 💥"
data-loading-text="⏱ Sending..."
hidden>Send Request 💥
</button>
</h3>
<p>
<small class="badge badge-black">POST</small>
<b><code>api/auth/login</code></b>
</p>
<h4 class="fancy-heading-panel"><b>Headers</b></h4>
<div style="padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>Authorization</code></b>&nbsp;&nbsp;
&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="Authorization" class="auth-value" data-endpoint="POSTapi-auth-login"
value="Bearer Bearer {token}"
data-component="header">
<br>
<p>Example: <code>Bearer Bearer {token}</code></p>
</div>
<div style="padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>Content-Type</code></b>&nbsp;&nbsp;
&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="Content-Type" data-endpoint="POSTapi-auth-login"
value="application/json"
data-component="header">
<br>
<p>Example: <code>application/json</code></p>
</div>
<div style="padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>Accept</code></b>&nbsp;&nbsp;
&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="Accept" data-endpoint="POSTapi-auth-login"
value="application/json"
data-component="header">
<br>
<p>Example: <code>application/json</code></p>
</div>
<h4 class="fancy-heading-panel"><b>Body Parameters</b></h4>
<div style=" padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>email</code></b>&nbsp;&nbsp;
<small>string</small>&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="email" data-endpoint="POSTapi-auth-login"
value="user@example.com"
data-component="body">
<br>
<p>User email address. Example: <code>user@example.com</code></p>
</div>
<div style=" padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>password</code></b>&nbsp;&nbsp;
<small>string</small>&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="password" data-endpoint="POSTapi-auth-login"
value="secret123"
data-component="body">
<br>
<p>User password. Example: <code>secret123</code></p>
</div>
</form>
<h2 id="authentication-POSTapi-auth-refresh">Refresh access token</h2>
<p>
<small class="badge badge-darkred">requires authentication</small>
</p>
<p>Exchange a valid refresh token for a new access token and refresh token pair.</p>
<span id="example-requests-POSTapi-auth-refresh">
<blockquote>Example request:</blockquote>
<div class="bash-example">
<pre><code class="language-bash">curl --request POST \
"http://localhost/api/api/auth/refresh" \
--header "Authorization: Bearer Bearer {token}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"refresh_token\": \"abc123def456\"
}"
</code></pre></div>
<div class="javascript-example">
<pre><code class="language-javascript">const url = new URL(
"http://localhost/api/api/auth/refresh"
);
const headers = {
"Authorization": "Bearer Bearer {token}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"refresh_token": "abc123def456"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response =&gt; response.json());</code></pre></div>
</span>
<span id="example-responses-POSTapi-auth-refresh">
<blockquote>
<p>Example response (200):</p>
</blockquote>
<pre>
<code class="language-json" style="max-height: 300px;">{
&quot;access_token&quot;: &quot;eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...&quot;,
&quot;refresh_token&quot;: &quot;newtoken123&quot;,
&quot;token_type&quot;: &quot;bearer&quot;,
&quot;expires_in&quot;: 3600
}</code>
</pre>
<blockquote>
<p>Example response (401):</p>
</blockquote>
<pre>
<code class="language-json" style="max-height: 300px;">{
&quot;message&quot;: &quot;Invalid or expired refresh token&quot;
}</code>
</pre>
</span>
<span id="execution-results-POSTapi-auth-refresh" hidden>
<blockquote>Received response<span
id="execution-response-status-POSTapi-auth-refresh"></span>:
</blockquote>
<pre class="json"><code id="execution-response-content-POSTapi-auth-refresh"
data-empty-response-text="<Empty response>" style="max-height: 400px;"></code></pre>
</span>
<span id="execution-error-POSTapi-auth-refresh" hidden>
<blockquote>Request failed with error:</blockquote>
<pre><code id="execution-error-message-POSTapi-auth-refresh">
Tip: Check that you&#039;re properly connected to the network.
If you&#039;re a maintainer of ths API, verify that your API is running and you&#039;ve enabled CORS.
You can check the Dev Tools console for debugging information.</code></pre>
</span>
<form id="form-POSTapi-auth-refresh" data-method="POST"
data-path="api/auth/refresh"
data-authed="1"
data-hasfiles="0"
data-isarraybody="0"
autocomplete="off"
onsubmit="event.preventDefault(); executeTryOut('POSTapi-auth-refresh', this);">
<h3>
Request&nbsp;&nbsp;&nbsp;
<button type="button"
style="background-color: #8fbcd4; padding: 5px 10px; border-radius: 5px; border-width: thin;"
id="btn-tryout-POSTapi-auth-refresh"
onclick="tryItOut('POSTapi-auth-refresh');">Try it out ⚡
</button>
<button type="button"
style="background-color: #c97a7e; padding: 5px 10px; border-radius: 5px; border-width: thin;"
id="btn-canceltryout-POSTapi-auth-refresh"
onclick="cancelTryOut('POSTapi-auth-refresh');" hidden>Cancel 🛑
</button>&nbsp;&nbsp;
<button type="submit"
style="background-color: #6ac174; padding: 5px 10px; border-radius: 5px; border-width: thin;"
id="btn-executetryout-POSTapi-auth-refresh"
data-initial-text="Send Request 💥"
data-loading-text="⏱ Sending..."
hidden>Send Request 💥
</button>
</h3>
<p>
<small class="badge badge-black">POST</small>
<b><code>api/auth/refresh</code></b>
</p>
<h4 class="fancy-heading-panel"><b>Headers</b></h4>
<div style="padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>Authorization</code></b>&nbsp;&nbsp;
&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="Authorization" class="auth-value" data-endpoint="POSTapi-auth-refresh"
value="Bearer Bearer {token}"
data-component="header">
<br>
<p>Example: <code>Bearer Bearer {token}</code></p>
</div>
<div style="padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>Content-Type</code></b>&nbsp;&nbsp;
&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="Content-Type" data-endpoint="POSTapi-auth-refresh"
value="application/json"
data-component="header">
<br>
<p>Example: <code>application/json</code></p>
</div>
<div style="padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>Accept</code></b>&nbsp;&nbsp;
&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="Accept" data-endpoint="POSTapi-auth-refresh"
value="application/json"
data-component="header">
<br>
<p>Example: <code>application/json</code></p>
</div>
<h4 class="fancy-heading-panel"><b>Body Parameters</b></h4>
<div style=" padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>refresh_token</code></b>&nbsp;&nbsp;
<small>string</small>&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="refresh_token" data-endpoint="POSTapi-auth-refresh"
value="abc123def456"
data-component="body">
<br>
<p>Refresh token returned by login. Example: <code>abc123def456</code></p>
</div>
</form>
<h2 id="authentication-POSTapi-auth-logout">Logout current session</h2>
<p>
<small class="badge badge-darkred">requires authentication</small>
</p>
<p>Invalidate a refresh token and end the active authenticated session.</p>
<span id="example-requests-POSTapi-auth-logout">
<blockquote>Example request:</blockquote>
<div class="bash-example">
<pre><code class="language-bash">curl --request POST \
"http://localhost/api/api/auth/logout" \
--header "Authorization: Bearer Bearer {token}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"refresh_token\": \"abc123def456\"
}"
</code></pre></div>
<div class="javascript-example">
<pre><code class="language-javascript">const url = new URL(
"http://localhost/api/api/auth/logout"
);
const headers = {
"Authorization": "Bearer Bearer {token}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"refresh_token": "abc123def456"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response =&gt; response.json());</code></pre></div>
</span>
<span id="example-responses-POSTapi-auth-logout">
<blockquote>
<p>Example response (200):</p>
</blockquote>
<pre>
<code class="language-json" style="max-height: 300px;">{
&quot;message&quot;: &quot;Logged out successfully&quot;
}</code>
</pre>
</span>
<span id="execution-results-POSTapi-auth-logout" hidden>
<blockquote>Received response<span
id="execution-response-status-POSTapi-auth-logout"></span>:
</blockquote>
<pre class="json"><code id="execution-response-content-POSTapi-auth-logout"
data-empty-response-text="<Empty response>" style="max-height: 400px;"></code></pre>
</span>
<span id="execution-error-POSTapi-auth-logout" hidden>
<blockquote>Request failed with error:</blockquote>
<pre><code id="execution-error-message-POSTapi-auth-logout">
Tip: Check that you&#039;re properly connected to the network.
If you&#039;re a maintainer of ths API, verify that your API is running and you&#039;ve enabled CORS.
You can check the Dev Tools console for debugging information.</code></pre>
</span>
<form id="form-POSTapi-auth-logout" data-method="POST"
data-path="api/auth/logout"
data-authed="1"
data-hasfiles="0"
data-isarraybody="0"
autocomplete="off"
onsubmit="event.preventDefault(); executeTryOut('POSTapi-auth-logout', this);">
<h3>
Request&nbsp;&nbsp;&nbsp;
<button type="button"
style="background-color: #8fbcd4; padding: 5px 10px; border-radius: 5px; border-width: thin;"
id="btn-tryout-POSTapi-auth-logout"
onclick="tryItOut('POSTapi-auth-logout');">Try it out ⚡
</button>
<button type="button"
style="background-color: #c97a7e; padding: 5px 10px; border-radius: 5px; border-width: thin;"
id="btn-canceltryout-POSTapi-auth-logout"
onclick="cancelTryOut('POSTapi-auth-logout');" hidden>Cancel 🛑
</button>&nbsp;&nbsp;
<button type="submit"
style="background-color: #6ac174; padding: 5px 10px; border-radius: 5px; border-width: thin;"
id="btn-executetryout-POSTapi-auth-logout"
data-initial-text="Send Request 💥"
data-loading-text="⏱ Sending..."
hidden>Send Request 💥
</button>
</h3>
<p>
<small class="badge badge-black">POST</small>
<b><code>api/auth/logout</code></b>
</p>
<h4 class="fancy-heading-panel"><b>Headers</b></h4>
<div style="padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>Authorization</code></b>&nbsp;&nbsp;
&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="Authorization" class="auth-value" data-endpoint="POSTapi-auth-logout"
value="Bearer Bearer {token}"
data-component="header">
<br>
<p>Example: <code>Bearer Bearer {token}</code></p>
</div>
<div style="padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>Content-Type</code></b>&nbsp;&nbsp;
&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="Content-Type" data-endpoint="POSTapi-auth-logout"
value="application/json"
data-component="header">
<br>
<p>Example: <code>application/json</code></p>
</div>
<div style="padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>Accept</code></b>&nbsp;&nbsp;
&nbsp;
&nbsp;
&nbsp;
<input type="text" style="display: none"
name="Accept" data-endpoint="POSTapi-auth-logout"
value="application/json"
data-component="header">
<br>
<p>Example: <code>application/json</code></p>
</div>
<h4 class="fancy-heading-panel"><b>Body Parameters</b></h4>
<div style=" padding-left: 28px; clear: unset;">
<b style="line-height: 2;"><code>refresh_token</code></b>&nbsp;&nbsp;
<small>string</small>&nbsp;
<i>optional</i> &nbsp;
&nbsp;
<input type="text" style="display: none"
name="refresh_token" data-endpoint="POSTapi-auth-logout"
value="abc123def456"
data-component="body">
<br>
<p>Optional refresh token to invalidate immediately. Example: <code>abc123def456</code></p>
</div>
</form>
</div>
<div class="dark-box">
<div class="lang-selector">
<button type="button" class="lang-button" data-language-name="bash">bash</button>
<button type="button" class="lang-button" data-language-name="javascript">javascript</button>
</div>
</div>
</div>
</body>
</html>