{"service":"fullstacked-cloud-docs","version":"1.22.3","environment":"live","generatedAt":"2026-10-24T09:40:10.248Z","formats":{"html":"https://docs.fullstacked.cloud/","markdown":"https://docs.fullstacked.cloud/?format=md","json":"https://docs.fullstacked.cloud/?format=json"},"services":{"console":"https://console.fullstacked.cloud","auth":"https://auth.fullstacked.cloud","git":"https://git.fullstacked.cloud","tunnels":"https://tunnels.fullstacked.cloud","tunnelsHost":"tunnels.fullstacked.cloud","mcp":"https://mcp.fullstacked.cloud","install":"https://install.fullstacked.cloud","docs":"https://docs.fullstacked.cloud"},"runtime":{"version":"1.0.0-alpha.1844","guide":"https://docs.fullstacked.cloud/runtime?format=md"},"dataEngineLimits":{"postgres":{"image":"postgres:18.6-alpine","port":5432,"memoryMB":256,"cpus":2,"pids":256},"redis":{"image":"redis:8.10.2-alpine","port":6379,"memoryMB":256,"cpus":1,"pids":128},"mongodb":{"image":"mongo:8.3.11-noble","port":27017,"memoryMB":512,"cpus":2,"pids":512},"s3":{"image":"rustfs/rustfs:1.0.0","port":9000,"memoryMB":768,"cpus":2,"pids":1024}},"projectRuntimeEnv":[{"name":"TUNNELS_HOST","injectedBy":"GET /api/v1/projects/:id/env","description":"Tunnels hub host for tunnel.register from fullstacked/tunnel."},{"name":"AUTH_HOST","injectedBy":"GET /api/v1/projects/:id/env","description":"Bare host of the Authentication service."},{"name":"AUTH_URL","injectedBy":"GET /api/v1/projects/:id/env","description":"Base URL of the Authentication service (GET ${AUTH_URL}/api/v1/me)."},{"name":"DOCS_URL","injectedBy":"GET /api/v1/projects/:id/env","description":"Base URL of this documentation (?format=md | ?format=json)."},{"name":"AUTH_TOKEN","injectedBy":"Client GUI / action runner at launch (in memory, never stored)","description":"The signed-in user's fsc_* bearer token: Authorization: Bearer ${AUTH_TOKEN}."}],"topics":[{"slug":"me","title":"Current User (/api/v1/me)","url":"https://docs.fullstacked.cloud/me","markdownUrl":"https://docs.fullstacked.cloud/me?format=md","jsonUrl":"https://docs.fullstacked.cloud/me?format=json","markdown":"# Current User (/api/v1/me)\n\nA project finds out who is running it by calling `GET ${process.env.AUTH_URL}/api/v1/me` with `Authorization: Bearer ${process.env.AUTH_TOKEN}`. The runtime's `fetch` sends it from the Go core, so there is no CORS issue and no backend to write: call it directly from `index.tsx`, a helper module or an action. For permissions, groups and quotas, call `GET ${process.env.AUTH_URL}/api/v1/user/access`.\n\n## Common mistakes\n\n| Mistake | What happens | Do instead |\n| :--- | :--- | :--- |\n| `fetch(\"/api/v1/me\")` | In an app, looks up the local files `out/api/v1/me` then `<project>/api/v1/me`, not found; in an action it throws (invalid URL) | `` fetch(`${process.env.AUTH_URL}/api/v1/me`, ...) `` |\n| A local `http.createServer` proxy | `http` has no `createServer` in the runtime | Call `fetch` from the code that needs the user |\n| Hardcoding `https://auth.fullstacked.cloud` | Breaks in the other environment | `process.env.AUTH_URL` |\n| No `Authorization` header | `401` | `` Authorization: `Bearer ${process.env.AUTH_TOKEN}` `` |\n\n## GET /api/v1/me\n\n- URL: `${process.env.AUTH_URL}/api/v1/me` (alias `/v1/me`), `https://auth.fullstacked.cloud/api/v1/me` here.\n- Auth: `Authorization: Bearer <fsc_* token>` (any native token: session, personal access token, agent, enterprise session).\n- Returns identity only, never grants. Errors: `401` (missing, unknown, revoked or expired token), `403` (account or authority suspended), body `{ \"error\", \"message\", \"statusCode\", \"details\" }`.\n\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"id\": \"usr_4f1c9a2b7d3e8f6a5b0c1d2e\",\n    \"username\": \"alice\",\n    \"slug\": \"alice\",\n    \"name\": \"Alice Martin\",\n    \"email\": \"alice@example.com\",\n    \"email_verified\": true,\n    \"avatar_url\": null,\n    \"type\": \"user\",\n    \"status\": \"active\",\n    \"plan\": \"base\",\n    \"plan_name\": \"Base\",\n    \"has_run_client_gui\": true,\n    \"restricted\": false,\n    \"created_at\": \"2026-09-20T14:32:00.000Z\"\n  }\n}\n```\n\n| Field | Meaning |\n| :--- | :--- |\n| `id` | `usr_<24 hex>` for platform users; `<authorityId>:<externalUserId>` for enterprise (BYOA) users. Use it as the stable user key. |\n| `username`, `slug` | Same value: the user's handle (Git namespace). Enterprise users: the external user id. |\n| `name`, `email` | May be `null`. `email` is always a verified address for platform users. |\n| `email_verified` | Platform users only. |\n| `avatar_url` | Always `null`: render initials or your own avatar. |\n| `type` | `user`, `operator`, `agent` (token issued to an AI agent) or `service_account` (Edge token). |\n| `plan`, `plan_name` | Platform users only: `base` or `pro` and its display name. |\n| `authority_id` | Enterprise users only: the issuing authority (`ath_<slug>`). |\n| `has_run_client_gui` | Whether this principal has run the FullStacked Cloud Client GUI. |\n| `restricted` | `true` while a platform user has not been invited to any asset yet. |\n| `created_at` | Account creation (enterprise users: token issue time), ISO 8601. |\n\n## Helper\n\n```ts\n// user.ts\nexport interface CurrentUser {\n    id: string;\n    username: string;\n    slug: string;\n    name: string | null;\n    email: string | null;\n    email_verified?: boolean;\n    avatar_url: string | null;\n    type: \"user\" | \"operator\" | \"agent\" | \"service_account\";\n    status: string;\n    plan?: \"base\" | \"pro\";\n    plan_name?: string;\n    authority_id?: string;\n    has_run_client_gui: boolean;\n    restricted: boolean;\n    created_at: string;\n}\n\nexport async function getCurrentUser(): Promise<CurrentUser> {\n    const { AUTH_URL, AUTH_TOKEN } = process.env;\n    if (!AUTH_URL || !AUTH_TOKEN) {\n        throw new Error(\"AUTH_URL / AUTH_TOKEN missing: run from the FullStacked Cloud Client GUI or with -e AUTH_TOKEN=...\");\n    }\n    const res = await fetch(`${AUTH_URL}/api/v1/me`, {\n        headers: { Authorization: `Bearer ${AUTH_TOKEN}`, Accept: \"application/json\" },\n    });\n    if (!res.ok) throw new Error(`GET /api/v1/me failed (${res.status}): ${await res.text()}`);\n    const body = (await res.json()) as { status: string; data: CurrentUser };\n    return body.data;\n}\n```\n\n```tsx\n// index.tsx\nimport React, { useEffect, useState } from \"react\";\nimport { createRoot } from \"react-dom/client\";\nimport { getCurrentUser, type CurrentUser } from \"./user\";\n\nfunction App() {\n    const [user, setUser] = useState<CurrentUser | null>(null);\n    const [error, setError] = useState<string | null>(null);\n    useEffect(() => {\n        getCurrentUser().then(setUser, (e) => setError(String(e?.message ?? e)));\n    }, []);\n    if (error) return <p>Not signed in: {error}</p>;\n    if (!user) return <p>Loading...</p>;\n    return <p>{user.name ?? user.username} ({user.email ?? \"no email\"})</p>;\n}\n\nconst root = document.createElement(\"div\");\ndocument.body.append(root);\ncreateRoot(root).render(<App />);\n```\n\nIn an action, the same helper returns the user who triggered the run (its `AUTH_TOKEN` is the caller's token).\n\n## GET /api/v1/user/access\n\n`GET ${process.env.AUTH_URL}/api/v1/user/access[?resource_type=projects|tunnels|data|mcp]`, same header. Returns `{ status: \"success\", data }` where `data` holds:\n\n| Key | Content |\n| :--- | :--- |\n| `principal` | The resolved principal. |\n| `user` | `id`, `username`, `slug?`, `name?`, `email?`, `email_verified?`, `type`, `status`, `plan?`. |\n| `billing` | Plan, quotas and usage. |\n| `groups` | `[{ id, name, inherited_roles }]`. |\n| `global_permissions` | Platform-wide permission strings. |\n| `resources.projects` | `[{ repository: <project UUID or \"*\">, permissions: { read, write, admin }, branches: { allow, deny }, tags: { allow, deny } }]`. |\n| `resources.tunnels` | `[{ host_pattern, can_register, can_connect }]`. |\n| `resources.data` | `{ <instance UUID>: { engine, read, write, delete? } }`. |\n\nEvery entry of `resources.projects`, `resources.tunnels` and `resources.data` also carries the quota flags `sponsored`, `frozen`, `freeze_reason` (`count`, `storage` or `null`) and `transfer_exhausted`. `resource_type` empties the other resource lists. Use it to gate UI (for example hide write actions unless `resources.data[id].write && !resources.data[id].frozen`: a frozen instance is read-only while `write` stays true); the platform enforces the same rules server side regardless.\n\n## Token hygiene\n\n`AUTH_TOKEN` grants everything the user can do. Send it only to `process.env.AUTH_URL`, other FullStacked Cloud services, the tunnels hub (inside `tunnel.register`) or a backend of yours that validates it (see [Runtime Sign-In & BYOA](https://docs.fullstacked.cloud/auth-byoa)). Never log it, render it, write it to a file or commit it.\n\n## Endpoints\n\n### GET /api/v1/me\n\nProfile of the bearer's principal: identity only, never grants or resources. BYOA principals add authority_id and omit email_verified, plan and plan_name.\n\n- **Service**: `auth` (`https://auth.fullstacked.cloud`)\n- **Auth**: Bearer fsc_* (AUTH_TOKEN)\n- **Aliases**: `/v1/me`\n- **In project code**: `${process.env.AUTH_URL}/api/v1/me`\n- **Pitfall**: A relative fetch(\"/api/v1/me\") reads the project's own static files: always prefix process.env.AUTH_URL.\n\nResponse:\n\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"id\": \"usr_0123456789abcdef01234567\",\n    \"username\": \"alice\",\n    \"slug\": \"alice\",\n    \"name\": \"Alice\",\n    \"email\": \"alice@example.com\",\n    \"email_verified\": true,\n    \"avatar_url\": null,\n    \"type\": \"user\",\n    \"status\": \"active\",\n    \"plan\": \"base\",\n    \"plan_name\": \"Base\",\n    \"has_run_client_gui\": true,\n    \"restricted\": false,\n    \"created_at\": \"2026-09-20T14:32:00.000Z\"\n  }\n}\n```\n\nindexTs:\n\n```ts\nconst res = await fetch(`${process.env.AUTH_URL}/api/v1/me`, {\n    headers: { Authorization: `Bearer ${process.env.AUTH_TOKEN}` },\n});\nconst { data: user } = await res.json();\n```\n\ncurl:\n\n```bash\ncurl -sS -H \"Authorization: Bearer $AUTH_TOKEN\" \"https://auth.fullstacked.cloud/api/v1/me\"\n```\n\n### GET /api/v1/user/access\n\nEffective access of the caller: principal, user, billing, groups, global_permissions and resources (projects, tunnels, data, mcp). Narrow with ?resource_type=projects|tunnels|data|mcp.\n\n- **Service**: `auth` (`https://auth.fullstacked.cloud`)\n- **Auth**: Bearer fsc_* (AUTH_TOKEN)\n- **In project code**: `${process.env.AUTH_URL}/api/v1/user/access`\n\ncurl:\n\n```bash\ncurl -sS -H \"Authorization: Bearer $AUTH_TOKEN\" \"https://auth.fullstacked.cloud/api/v1/user/access?resource_type=projects\"\n```\n"}],"endpoints":[{"service":"auth","topic":"me","id":"auth.me","method":"GET","path":"/api/v1/me","aliases":["/v1/me"],"auth":"Bearer fsc_* (AUTH_TOKEN)","summary":"Profile of the bearer's principal: identity only, never grants or resources. BYOA principals add authority_id and omit email_verified, plan and plan_name.","inProjectUrlExpression":"${process.env.AUTH_URL}/api/v1/me","commonPitfall":"A relative fetch(\"/api/v1/me\") reads the project's own static files: always prefix process.env.AUTH_URL.","responseExample":{"status":"success","data":{"id":"usr_0123456789abcdef01234567","username":"alice","slug":"alice","name":"Alice","email":"alice@example.com","email_verified":true,"avatar_url":null,"type":"user","status":"active","plan":"base","plan_name":"Base","has_run_client_gui":true,"restricted":false,"created_at":"2026-09-20T14:32:00.000Z"}},"codeExamples":{"indexTs":"const res = await fetch(`${process.env.AUTH_URL}/api/v1/me`, {\n    headers: { Authorization: `Bearer ${process.env.AUTH_TOKEN}` },\n});\nconst { data: user } = await res.json();","curl":"curl -sS -H \"Authorization: Bearer $AUTH_TOKEN\" \"https://auth.fullstacked.cloud/api/v1/me\""},"fullUrl":"https://auth.fullstacked.cloud/api/v1/me"},{"service":"auth","topic":"me","id":"auth.userAccess","method":"GET","path":"/api/v1/user/access","auth":"Bearer fsc_* (AUTH_TOKEN)","summary":"Effective access of the caller: principal, user, billing, groups, global_permissions and resources (projects, tunnels, data, mcp). Narrow with ?resource_type=projects|tunnels|data|mcp.","inProjectUrlExpression":"${process.env.AUTH_URL}/api/v1/user/access","codeExamples":{"curl":"curl -sS -H \"Authorization: Bearer $AUTH_TOKEN\" \"https://auth.fullstacked.cloud/api/v1/user/access?resource_type=projects\""},"fullUrl":"https://auth.fullstacked.cloud/api/v1/user/access"}]}