Authenticating requests to the ManticsCore API

ManticsCore supports two ways to obtain a session token:

Authenticated sessions — start from a Clerk JWT and exchange it for an opaque session token tied to your Clerk user id.
Anonymous sessions — start from a stable device id (no sign-in required) and receive a session token tied to an anonymous principal. When the user later signs in, a single rebind call re-owns every anonymous artifact to the authenticated account.

Session tokens are validated in O(1) time on the server, making them significantly faster than repeated JWT verification.

Step 1 — Get a Clerk JWT

Obtain a short-lived Clerk JWT using the Clerk frontend SDK appropriate for your platform. Refer to the Clerk documentation for platform-specific instructions. You’ll use this JWT exactly once: to mint a session token.

Step 2 — Exchange for a session token

Call POST /auth/session with your Clerk JWT in the Authorization header. The server verifies the JWT, creates a session, and returns an opaque session token.

POST /auth/session only accepts a Clerk JWT. You cannot use an existing session token to mint a new one — call this endpoint with your Clerk JWT each time you need to refresh.

curl -X POST https://api.manticscore.com/auth/session \
  -H "Authorization: Bearer <clerk_jwt>"

import httpx

response = httpx.post(
    "https://api.manticscore.com/auth/session",
    headers={"Authorization": f"Bearer {clerk_jwt}"},
)
data = response.json()
session_token = data["token"]

const response = await fetch("https://api.manticscore.com/auth/session", {
  method: "POST",
  headers: { Authorization: `Bearer ${clerkJwt}` },
});
const { token } = await response.json();

Request parameters

string

required

Your Clerk JWT. Format: Bearer <clerk_jwt>.

Response

200 response

{
  "token": "ms_sess_a1b2c3d4e5f6...",
  "expires_in": 1800
}

string

required

Opaque session token. Treat this like a password — store it securely and never log it.

number

required

Seconds until the token expires. Always 1800 (30 minutes).

Step 3 — Attach the session token to requests

Include the session token as a Bearer token on every protected endpoint:

Authorization: Bearer <session_token>

curl https://api.manticscore.com/projects \
  -H "Authorization: Bearer ms_sess_a1b2c3d4e5f6..."

import httpx

headers = {"Authorization": f"Bearer {session_token}"}
projects = httpx.get("https://api.manticscore.com/projects", headers=headers).json()

const projects = await fetch("https://api.manticscore.com/projects", {
  headers: { Authorization: `Bearer ${sessionToken}` },
}).then((r) => r.json());

Refreshing session tokens

Session tokens expire after 30 minutes. To refresh, call POST /auth/session again with a fresh Clerk JWT before the current token expires. You can do this proactively — for example, refresh 5 minutes before expiry rather than waiting for a 401 Token expired response.

Refresh proactively in long-running apps. If you let the token expire mid-stream, the NDJSON connection will close and you’ll need to reconnect.

Logging out

Revoking a token immediately invalidates it server-side. Any in-flight requests using the revoked token will fail with 401.

curl -X DELETE https://api.manticscore.com/auth/session \
  -H "Authorization: Bearer ms_sess_a1b2c3d4e5f6..."

import httpx

httpx.delete(
    "https://api.manticscore.com/auth/session",
    headers={"Authorization": f"Bearer {session_token}"},
)

await fetch("https://api.manticscore.com/auth/session", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${sessionToken}` },
});

200 response

{
  "success": true
}

Bootstrap — hydrate your app on launch

After authenticating, call GET /auth/bootstrap as your first API request. It returns your profile, subscription details, and integration secrets in a single round trip. If this is your first sign-in, the server auto-creates your profile.

curl https://api.manticscore.com/auth/bootstrap \
  -H "Authorization: Bearer ms_sess_a1b2c3d4e5f6..."

import httpx

bootstrap = httpx.get(
    "https://api.manticscore.com/auth/bootstrap",
    headers={"Authorization": f"Bearer {session_token}"},
).json()

const bootstrap = await fetch("https://api.manticscore.com/auth/bootstrap", {
  headers: { Authorization: `Bearer ${sessionToken}` },
}).then((r) => r.json());

200 response

{
  "profile": {
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "plan": "free",
    "credits_used": 3,
    "credits_total": 20
  },
  "subscription": {
    "plan": "free",
    "credits_used": 3,
    "credits_total": 20
  },
  "secrets": {
    "has_github_pat": true,
    "has_anthropic_key": false
  }
}

object

required

Show properties

string

Display name on the account.

string

Email address on the account.

string

Subscription tier. Currently free or pro.

number

Credits consumed in the current billing window.

number

Total credits available in the current billing window.

object

required

Current subscription state. Mirrors the credit fields in profile for convenience.

object

required

Show properties

boolean

Whether you have a GitHub personal access token stored.

boolean

Whether you have an Anthropic API key stored.

Start an anonymous session

Call POST /auth/anonymous with a stable device_id to mint a session token without any sign-in. Use this on first launch to let users try the product before creating an account. The returned token behaves like any other session token — attach it with Authorization: Bearer <token> on subsequent requests. This endpoint is unauthenticated (no Authorization header required) and idempotent on device_id: calling it again for the same device returns a session bound to the same anonymous principal.

curl -X POST https://api.manticscore.com/auth/anonymous \
  -H "Content-Type: application/json" \
  -d '{"device_id": "<device_id>"}'

import httpx

response = httpx.post(
    "https://api.manticscore.com/auth/anonymous",
    json={"device_id": device_id},
)
data = response.json()
session_token = data["token"]

const response = await fetch("https://api.manticscore.com/auth/anonymous", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ device_id: deviceId }),
});
const { token } = await response.json();

Request body

string

required

Stable per-device identifier (1–200 chars). On iOS, use identifierForVendor or a Keychain-persisted UUID so the same device keeps the same anonymous principal across launches.

Response

200 response

{
  "token": "ms_sess_a1b2c3d4e5f6...",
  "expires_in": 1800
}

string

required

Opaque session token for the anonymous principal. Use it the same way as an authenticated session token.

number

required

Seconds until the token expires. Always 1800 (30 minutes).

Anonymous writes are tagged internally with a sentinel user_id of the form anon:<uuid>. You should not rely on that string shape — treat the session token as opaque. Once the user signs in and you call POST /auth/rebind, every anonymous artifact is re-owned by the Clerk user in a single transaction.

Errors

Status	Body	Cause
`422`	`{"detail": "device_id required"}`	`device_id` is missing or empty

Rebind an anonymous session to a signed-in user

After a user signs in with Clerk, call POST /auth/rebind with the original device_id and the authenticated session token (or Clerk JWT) in the Authorization header. Every row written under the anonymous principal is re-owned by the authenticated user in a single database transaction, and a durable PostHog alias call is enqueued so conversion attribution survives transient analytics failures.

curl -X POST https://api.manticscore.com/auth/rebind \
  -H "Authorization: Bearer <authenticated_session_token>" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "<device_id>"}'

import httpx

response = httpx.post(
    "https://api.manticscore.com/auth/rebind",
    headers={"Authorization": f"Bearer {session_token}"},
    json={"device_id": device_id},
)
result = response.json()

const response = await fetch("https://api.manticscore.com/auth/rebind", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${sessionToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ device_id: deviceId }),
});
const result = await response.json();

Request body

string

required

The same device_id used when calling POST /auth/anonymous. Must be 1–200 chars.

Response

200 response

{
  "rebound": true,
  "rows_updated": 14,
  "anon_uuid": "b1e4..."
}

boolean

required

true when this call transferred artifacts to the authenticated user. false when the call was a no-op (for example, the device had no anonymous principal, or it was already rebound to the same user).

number

required

Total number of rows re-owned across all user-scoped tables. 0 when rebound is false.

string | null

required

The anonymous principal UUID that was rebound, or null when there was nothing to rebind.

POST /auth/rebind is safe to call defensively after every sign-in. If the device never used an anonymous session, or the same device/user pair has already been rebound, the call is a no-op and returns {"rebound": false}.

Errors

Status	Body	Cause
`401`	`{"detail": "Rebind requires an authenticated user token; got anonymous session"}`	The `Authorization` header carried an anonymous session token. Sign the user in first, then call rebind with the authenticated token.
`409`	`{"detail": "device <id> already rebound to a different user"}`	This device was previously rebound to a different Clerk user. Human intervention is required.
`422`	`{"detail": "device_id and clerk_user_id required"}`	The `device_id` field is missing from the body.

Auth error reference

Status	Body	What to do
`401`	`{"detail": "Missing Bearer token"}`	Add an `Authorization: Bearer <token>` header
`401`	`{"detail": "Token expired"}`	Call `POST /auth/session` to get a new session token
`401`	`{"detail": "Invalid token: ..."}`	Check that the token was copied correctly and hasn’t been tampered with
`503`	`{"detail": "JWKS not loaded"}`	The auth service is temporarily unavailable — retry in a few seconds

Overview

Projects & Research

Build & Forge

Intelligence & Chat

Integrations & Ship

Pipeline & Realtime

Billing & Admin

Authenticating requests to the ManticsCore API

Step 1 — Get a Clerk JWT

Step 2 — Exchange for a session token

Step 3 — Attach the session token to requests

Refreshing session tokens

Logging out

Bootstrap — hydrate your app on launch

Start an anonymous session

Rebind an anonymous session to a signed-in user

Auth error reference

​Step 1 — Get a Clerk JWT

​Step 2 — Exchange for a session token

​Step 3 — Attach the session token to requests

​Refreshing session tokens

​Logging out

​Bootstrap — hydrate your app on launch

​Start an anonymous session

​Rebind an anonymous session to a signed-in user

​Auth error reference

Step 1 — Get a Clerk JWT

Step 2 — Exchange for a session token

Step 3 — Attach the session token to requests

Refreshing session tokens

Logging out

Bootstrap — hydrate your app on launch

Start an anonymous session

Rebind an anonymous session to a signed-in user

Auth error reference