Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt

Use this file to discover all available pages before exploring further.

Meridian uses cookie-based authentication. When you log in, the API sets a secure session cookie in your browser — you don’t manage tokens manually. Every subsequent request your browser makes automatically includes that cookie, so you stay logged in until you explicitly log out or the session expires.

​
Logging in

Send a POST request to /auth/login with your email and password: 
POST /auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}
On success, the API returns your access token details and sets an auth-token HttpOnly cookie in your browser. You don’t need to store or forward this token yourself — the browser handles it automatically. 
{
  "access_token": "...",
  "token_type": "Bearer"
}

​
Two-factor authentication

If your account has two-factor authentication (2FA) enabled, the login response looks different: 
{
  "requires_2fa": true,
  "two_factor_token": "..."
}
When you receive requires_2fa: true, prompt for the 6-digit code from your authenticator app and send it to /auth/2fa/verify: 
POST /auth/2fa/verify
Content-Type: application/json

{
  "two_factor_token": "<token from login response>",
  "code": "123456"
}
On success, the session cookie is set and you’re fully logged in.

​
How sessions work

The auth-token cookie is set with the following properties:
  • HttpOnly — JavaScript cannot read the cookie, which protects against cross-site scripting (XSS) attacks.
  • Secure — the cookie is only sent over HTTPS connections.
  • SameSite=None — allows the cookie to be sent on cross-origin requests, which is required when your frontend and API run on different domains.
  • Expires in 30 days — after 30 days of inactivity, the session expires and you’ll need to log in again.
You don’t need to write any cookie-handling code. As long as your HTTP client is configured to send credentials with each request, the browser manages the rest.

​
Checking if you’re logged in

To verify the current session and retrieve the authenticated user’s details, call GET /auth/me: 
GET /auth/me
A successful response returns your user profile: 
{
  "success": true,
  "data": {
    "uuid": "...",
    "email": "you@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "active_organization": {
      "uuid": "...",
      "name": "My App Studio",
      "slug": "my-app-studio"
    },
    "can_create_organizations": true
  }
}
The active_organization field tells you which workspace is currently selected. If it’s null, navigate to the organization switcher to select a workspace.
Call GET /auth/me on app load to restore session state without requiring the user to log in again on every page refresh.

​
Logging out

Send a POST request to /auth/logout to end the session: 
POST /auth/logout
The API clears the auth-token cookie and invalidates the session. After logging out, any protected request will return a 401 Unauthorized response.

​
API base URL

All Meridian API endpoints live under the /app prefix. For example, the login endpoint is /app/auth/login. When making API calls directly, construct your request URLs relative to the base domain provided in your Meridian workspace settings.
The base path prefix is /app. If your requests are returning 404s, verify that you are including this prefix — e.g., https://api.meridian.app/app/auth/login.

​
Handling 401 errors

A 401 Unauthorized response means the request was made without a valid session, or the session has expired. This happens when:
  • You’re not logged in yet.
  • Your 30-day session has expired.
  • The session cookie was cleared (for example, by logging out or clearing browser data).
When you receive a 401, redirect the user to the login page. After they log in, the session cookie is refreshed and subsequent requests will succeed.

​
Troubleshooting

​
Cookies are not being saved after login

If you log in successfully but the session cookie doesn’t appear in your browser:
  1. Confirm both your frontend and API use HTTPS. The auth-token cookie has the Secure flag, which means browsers refuse to store it over plain HTTP.
  2. Check the CORS headers on the API response. The response must include Access-Control-Allow-Credentials: true and Access-Control-Allow-Origin set to your exact frontend URL — wildcards (*) do not work with credentialed requests.
  3. Open browser DevTools → Application → Cookies and verify that auth-token appears under your API domain after login.
  4. Confirm your HTTP client sends credentials. If you’re making requests programmatically, set withCredentials: true (Axios) or credentials: 'include' (Fetch).

​
Requests return 401 even though I’m logged in

  1. Open browser DevTools → Network, click the failing request, and check the Request Headers tab. Confirm the Cookie header is present and contains auth-token.
  2. If the cookie is missing from the request, see the steps above — the cookie likely wasn’t saved correctly at login.
  3. If the cookie is present but you still get a 401, the session may have expired. Log in again to get a fresh session.

​
CORS errors in the browser console

CORS errors during login or authenticated requests almost always mean the API’s Access-Control-Allow-Origin header doesn’t match your frontend’s exact origin. Ensure the API is configured to allow your frontend domain (including the protocol and port). Wildcards are not compatible with Access-Control-Allow-Credentials: true.
Never set Access-Control-Allow-Origin: * alongside Access-Control-Allow-Credentials: true. Browsers block this combination and your cookies will not be sent.
Last modified on May 5, 2026