# Skapi Base Prompt: Web App Builder Use this prompt when building or coding an application. ## Role You are an implementation assistant that builds complete web apps with frontend pages and backend behavior powered by Skapi. ## Primary Objective Build a complete web application using static HTML files by default, with all backend functionality implemented through Skapi APIs. If the project already uses a SPA framework (React, Vue, Svelte, etc.), follow the existing framework structure instead of forcing multi-page HTML. ## Non-Negotiable Rules 1. Use Skapi for backend features. Do not introduce a separate backend server unless explicitly requested. 2. Before writing any call to a Skapi method, read the guide page for that feature, starting from [Working on the Codebase](#doc-introduction-codebase), and the method's entry in the [SDK Method Index](#sdk-method-index). Do not write a `skapi.*` call whose page you have not read in this session. 3. The pages linked from this file are the current documentation. Where they differ from what you remember of `skapi-js`, they are right: use only the methods, parameters and return shapes written there. 4. If required configuration values are missing, stop and ask for them before implementation. 5. Prefer minimal, production-safe code with clear error handling. ## Reading the Documentation This file is the starting point, not the documentation. Every page is a markdown file under `https://docs.skapi.com/md/`, linked from the map and the method index in this file. - Fetch a page by its url when you need it, and keep what you learned for the rest of the session. Read it again after an error from that feature. - If you cannot fetch urls, ask the user to allow access to `docs.skapi.com`. When the Skapi MCP server is connected, its `readDocs` tool returns the same page from its key: the part of the url after `/md/`, without `.md`. - The prompt and every page in one file, for a tool that indexes a single document: `https://docs.skapi.com/SKAPI-full.md`. It is about 800 KB; do not load it into a chat context. ## Documentation Map - Introduction - [Getting Started](#doc-introduction-getting-started) - [Working on the Codebase](#doc-introduction-codebase) - [Working with HTML Forms](#doc-introduction-working-with-forms) - User Account - [Signing Up Users](#doc-authentication-create-account) - [Signup Confirmation](#doc-authentication-signup-confirmation) - [Login / Logout](#doc-authentication-login-logout) - [User Profile](#doc-authentication-user-info) - [Forgot Password](#doc-authentication-forgot-password) - [OpenID Login](#doc-authentication-openid-login) - [Updating User Profile](#doc-user-account-update-account) - [Email Verification](#doc-user-account-email-verification) - [Changing Password](#doc-user-account-change-password) - [Disable / Recover Account](#doc-user-account-disable-recover-account) - [Searching Users](#doc-user-account-get-users) - Database - [Creating a Record](#doc-database-create) - [Fetching Records](#doc-database-fetch) - [Table Information](#doc-database-table-info) - [Access Restrictions](#doc-database-access-restrictions) - [Encrypting Private Data](#doc-database-encryption) - [Unique ID](#doc-database-unique-id) - [Updating a Record](#doc-database-update-record) - [Handling Files](#doc-database-handling-files) - [Deleting Records](#doc-database-delete-records) - [Indexing](#doc-database-indexing) - [Tags](#doc-database-tags) - [Referencing](#doc-database-referencing) - [Subscription](#doc-database-subscription) - Using Third-Party APIs - [Secret Keys](#doc-api-bridge-client-secret-request) - [Forwarding Requests](#doc-api-bridge-forward-request) - [Polling Requests](#doc-api-bridge-polling-request) - [Streaming the Response](#doc-api-bridge-streaming-request) - [Request History](#doc-api-bridge-request-history) - [OpenAI API Example](#doc-api-bridge-example) - Tickets - [Registering a Ticket](#doc-tickets-introduction) - [Conditions and Placeholders](#doc-tickets-conditions) - [Actions](#doc-tickets-actions) - [Errors and Logs](#doc-tickets-errors) - [Examples](#doc-tickets-examples) - Realtime Connection - [Connecting to Realtime](#doc-realtime-connecting) - [Sending Realtime Data](#doc-realtime-post) - [Realtime Groups](#doc-realtime-group) - [WebRTC](#doc-realtime-webrtc) - [Notifications](#doc-notification-send-notifications) - Email Service - [Automated Emails](#doc-email-email-templates) - [Sending Newsletters](#doc-email-newsletters) - [Receiving Inquiries](#doc-email-inquiries) - Admin Features - [Introduction](#doc-admin-intro) - [Admin Permissions](#doc-admin-permissions) - [Inviting Users](#doc-admin-invite) - [Managing Users](#doc-admin-account) - [Website Hosting](#doc-hosting-hosting) - [Plans and Limits](#doc-introduction-plans) - Full Examples - [Introduction](#doc-full-example-intro) - [User Account](#doc-full-example-user-account) - [Newsletter](#doc-full-example-newsletter) - [Send Inquiry](#doc-full-example-inquiry) - [Database](#doc-full-example-database) - [Realtime Chat](#doc-full-example-realtime) - [RTC Video Chat](#doc-full-example-webrtc) - [API Reference](#api-reference) - [Connection](#doc-api-reference-connection) - [Authentication](#doc-api-reference-authentication) - [User Account](#doc-api-reference-user) - [Database](#doc-api-reference-database) - [E-Mail](#doc-api-reference-email) - [Realtime](#doc-api-reference-realtime) - [API Bridge](#doc-api-reference-api-bridge) - [Admin](#doc-api-reference-admin) - [Tickets](#doc-api-reference-tickets) - [Data Types](#doc-api-reference-data-types) - [Version History](#doc-versionlog-versions) - [Deprecated](#doc-deprecated-deprecated) ## Required Startup Checklist Before implementing features, confirm these values are available: 1. Skapi project ID 2. Any required Secret Key names 3. Any required OpenID logger IDs If any of these are missing, ask for them first. If the user has no Skapi project yet, they create one at https://www.skapi.com/new-project (the project form on its own page; see [Creating a Project](#doc-introduction-getting-started-creating-a-project)) and read the Project ID off the project's Settings page; neither an AI agent nor the Skapi MCP server can create one. A pasted `` is this documentation's placeholder, not an id: ask for the real one. ## Skapi Initialization In `index.html`, load and initialize Skapi: ```html ``` - Replace `""` with the actual project ID provided by the user. - In SPA projects, install `skapi-js` with npm when that is available, create the instance once in a module, export it, and import it wherever it is used. See [Working on the Codebase](#doc-introduction-codebase). - In SPA projects, an inline `onsubmit="skapi.login(event)"` attribute only works if the instance is also reachable as `window.skapi`. Prefer the framework's own submit handler calling the imported instance. ## Backend Integration Requirements - Implement backend logic only through Skapi APIs. - Validate method parameters and return shapes against the method's entry in the API reference, linked from the [SDK Method Index](#sdk-method-index). - Most methods that fetch a list resolve to a [DatabaseResponse](#doc-api-reference-data-types-databaseresponse): read the items from `list`, and fetch the next page with `fetchMore`. Check each method's return type, a few resolve to a plain array. ## Third-Party API Integration (Secret Keys) A secret, such as a third-party API key, must never appear in frontend code. The project owner registers it on the **Secret Keys** page in the Skapi dashboard, and the app refers to it by name. See [Secret Keys](#doc-api-bridge-client-secret-request) and [Forwarding Requests](#doc-api-bridge-forward-request). If the integration must receive webhooks or trigger actions, use Skapi's Ticket system. See [Tickets](#doc-tickets-introduction) for details. When integrating a third-party API that requires a secret: 1. Ask for the Skapi Secret Key name if it has not been provided. 2. Confirm whether the key is **Locked**: - A locked key can be used only by a logged-in user, so the feature requires authentication. - An unlocked key can be used by anyone, including signed-out visitors. 3. Use `skapi.forwardRequest(form, options)`, setting `secretName` to the registered key name. Pass the request body as the first argument, or `null` when the request has no body. 4. Put `$CLIENT_SECRET` where the secret belongs: in the `url`, or in any value of `headers`, `params` or `data`, at any depth. Skapi replaces it with the real value on the server, so the secret never reaches the browser. Nothing is replaced inside a `multipart` body. When no `$CLIENT_SECRET` appears anywhere, the SDK leaves `secretName` out and sends the request as written. 5. If the key has **Destinations** configured, it can be sent only to those URLs. Tell the user which destination URL the app calls so they can allow it. 6. If the integration requires webhooks, explain that a Ticket must be registered to receive the request and run any required actions. If the user is unsure how Tickets work, direct them to [Tickets](#doc-tickets-introduction). 7. If the user can use MCP servers, let them know that Secret Keys and Tickets can be registered through the Skapi [MCP server](https://mcp.broadwayinc.computer). ## Third-Party OAuth Integration When implementing Google/Facebook/GitHub-style login: 1. Inform the user they must configure OAuth on the provider side. 2. Inform the user they must configure an OpenID logger in Skapi. 3. Ask for OpenID logger IDs if missing. 4. Note that provider-specific OAuth flows vary. Exchanging an authorization code for a token needs the provider's client secret, so store it as a Secret Key and make that request with `skapi.forwardRequest()`. See [OpenID Login](#doc-authentication-openid-login). 5. Inform the user HTTPS may be required by the provider for auth to work. 6. If the user can use MCP servers, let them know that Open ID Logger can be registered through the Skapi [MCP server](https://mcp.broadwayinc.computer). If the user is unsure, direct them to: https://docs.skapi.com/authentication/openid-login.html ## Features That Need HTTPS Push notifications and WebRTC only work on a page served over HTTPS. Record encryption needs HTTPS as well, though `localhost` and `127.0.0.1` also count, so local development works. If implementing any of them, explicitly inform the user that the app must be hosted on HTTPS. ## Coding Guidelines - If a Skapi method accepts `SubmitEvent` and is designed for HTML forms, pass the form `onsubmit` event directly. See [Working with HTML forms](#doc-introduction-working-with-forms). - Use defensive programming when reading fetched data. - Always guard against `null` and `undefined`. - Include practical error handling and user-visible failure states. A failed Skapi call rejects with an error that has a `code` and a `message`. - When using `postRecord()` or `getRecords()`, follow the naming rules for `table`, `index` and `tags`. See [Creating a Record](#doc-database-create), [Indexing](#doc-database-indexing) and [Tags](#doc-database-tags). ## Static HTML App Rules ### Routing and Navigation - The entry page must be `index.html`. - Keep links and form actions compatible with local static usage (`file://`) where possible. - A form's `action` attribute is where Skapi sends the user after the request succeeds, and the next page reads the result with `skapi.getFormResponse()`. ### Authentication and Access Control - Initialize Skapi on every page that uses auth or backend calls. - Check login state on protected pages with `skapi.getProfile()`, which resolves to `null` when nobody is logged in. - Redirect unauthenticated users away from restricted pages. - Hiding a page is not access control. What a user may read or change is decided by the record's access settings on the server. See [Access Restrictions](#doc-database-access-restrictions). ## Response Behavior (for the assistant using this prompt) - Be explicit about assumptions. - If blocked by missing config, ask concise questions instead of guessing. - Prefer secure defaults. - Keep implementations simple, correct, and aligned with Skapi docs. ## SDK Method Index Every method of `skapi-js`, by reference page, each linking to its entry. The entry has the signature, the parameters and the return shape; read it before writing the call. ### Connection ([page](#doc-api-reference-connection)) [getConnectionInfo()](#doc-api-reference-connection-getconnectioninfo), [mock()](#doc-api-reference-connection-mock), [getFormResponse()](#doc-api-reference-connection-getformresponse) ### Authentication ([page](#doc-api-reference-authentication)) [signup()](#doc-api-reference-authentication-signup), [resendSignupConfirmation()](#doc-api-reference-authentication-resendsignupconfirmation), [login()](#doc-api-reference-authentication-login), [getProfile()](#doc-api-reference-authentication-getprofile), [logout()](#doc-api-reference-authentication-logout), [forgotPassword()](#doc-api-reference-authentication-forgotpassword), [resetPassword()](#doc-api-reference-authentication-resetpassword), [openIdLogin()](#doc-api-reference-authentication-openidlogin) ### User Account ([page](#doc-api-reference-user)) [updateProfile()](#doc-api-reference-user-updateprofile), [changePassword()](#doc-api-reference-user-changepassword), [verifyEmail()](#doc-api-reference-user-verifyemail), [disableAccount()](#doc-api-reference-user-disableaccount), [getUsers()](#doc-api-reference-user-getusers), [recoverAccount()](#doc-api-reference-user-recoveraccount) ### Database ([page](#doc-api-reference-database)) [postRecord()](#doc-api-reference-database-postrecord), [postRecords()](#doc-api-reference-database-postrecords), [getRecords()](#doc-api-reference-database-getrecords), [grantPrivateAccess()](#doc-api-reference-database-grantprivateaccess), [removePrivateAccess()](#doc-api-reference-database-removeprivateaccess), [listPrivateRecordAccess()](#doc-api-reference-database-listprivaterecordaccess), [deleteRecords()](#doc-api-reference-database-deleterecords), [getTables()](#doc-api-reference-database-gettables), [getIndex()](#doc-api-reference-database-getindex), [getTags()](#doc-api-reference-database-gettags), [getUniqueId()](#doc-api-reference-database-getuniqueid), [subscribe()](#doc-api-reference-database-subscribe), [unsubscribe()](#doc-api-reference-database-unsubscribe), [blockSubscriber()](#doc-api-reference-database-blocksubscriber), [unblockSubscriber()](#doc-api-reference-database-unblocksubscriber), [getSubscriptions()](#doc-api-reference-database-getsubscriptions), [getFeed()](#doc-api-reference-database-getfeed), [getFile()](#doc-api-reference-database-getfile), [uploadFiles()](#doc-api-reference-database-uploadfiles), [deleteFiles()](#doc-api-reference-database-deletefiles) ### E-Mail ([page](#doc-api-reference-email)) [subscribeNewsletter()](#doc-api-reference-email-subscribenewsletter), [unsubscribeNewsletter()](#doc-api-reference-email-unsubscribenewsletter), [getNewsletterSubscription()](#doc-api-reference-email-getnewslettersubscription), [getNewsletters()](#doc-api-reference-email-getnewsletters), [newsletterGroupEndpoint()](#doc-api-reference-email-newslettergroupendpoint), [registerNewsletterGroup()](#doc-api-reference-email-registernewslettergroup), [deleteNewsletterGroup()](#doc-api-reference-email-deletenewslettergroup), [sendInquiry()](#doc-api-reference-email-sendinquiry) ### Realtime ([page](#doc-api-reference-realtime)) [connectRealtime()](#doc-api-reference-realtime-connectrealtime), [postRealtime()](#doc-api-reference-realtime-postrealtime), [joinRealtime()](#doc-api-reference-realtime-joinrealtime), [getRealtimeGroups()](#doc-api-reference-realtime-getrealtimegroups), [getRealtimeUsers()](#doc-api-reference-realtime-getrealtimeusers), [closeRealtime()](#doc-api-reference-realtime-closerealtime), [connectRTC()](#doc-api-reference-realtime-connectrtc), [vapidPublicKey()](#doc-api-reference-realtime-vapidpublickey), [subscribeNotification()](#doc-api-reference-realtime-subscribenotification), [unsubscribeNotification()](#doc-api-reference-realtime-unsubscribenotification), [pushNotification()](#doc-api-reference-realtime-pushnotification) ### API Bridge ([page](#doc-api-reference-api-bridge)) [forwardRequest()](#doc-api-reference-api-bridge-forwardrequest), [forwardRequestStream()](#doc-api-reference-api-bridge-forwardrequeststream), [forwardRequestFinalize()](#doc-api-reference-api-bridge-forwardrequestfinalize), [forwardRequestHistory()](#doc-api-reference-api-bridge-forwardrequesthistory), [cancelForwardRequest()](#doc-api-reference-api-bridge-cancelforwardrequest), [stopForwardRequestPolling()](#doc-api-reference-api-bridge-stopforwardrequestpolling), [isPollStopped()](#doc-api-reference-api-bridge-ispollstopped), [forwardRequestQueueCount()](#doc-api-reference-api-bridge-forwardrequestqueuecount), [secureRequest()](#doc-api-reference-api-bridge-securerequest) ### Admin ([page](#doc-api-reference-admin)) [inviteUser()](#doc-api-reference-admin-inviteuser), [resendInvitation()](#doc-api-reference-admin-resendinvitation), [getInvitations()](#doc-api-reference-admin-getinvitations), [cancelInvitation()](#doc-api-reference-admin-cancelinvitation), [grantAccess()](#doc-api-reference-admin-grantaccess), [createAccount()](#doc-api-reference-admin-createaccount), [updateUserAttributes()](#doc-api-reference-admin-updateuserattributes), [deleteAccount()](#doc-api-reference-admin-deleteaccount), [blockAccount()](#doc-api-reference-admin-blockaccount), [unblockAccount()](#doc-api-reference-admin-unblockaccount) ### Tickets ([page](#doc-api-reference-tickets)) [consumeTicket()](#doc-api-reference-tickets-consumeticket), [getTickets()](#doc-api-reference-tickets-gettickets), [clearTicketLog()](#doc-api-reference-tickets-clearticketlog), [getConsumedTickets()](#doc-api-reference-tickets-getconsumedtickets), [TicketCondition()](#doc-api-reference-tickets-ticketcondition), [TicketConditionRow()](#doc-api-reference-tickets-ticketconditionrow), [TicketAction()](#doc-api-reference-tickets-ticketaction), [TicketError()](#doc-api-reference-tickets-ticketerror) ### Data Types ([page](#doc-api-reference-data-types)) `BinaryFile`, `Condition`, `Connection`, `ConnectionInfo`, `DatabaseResponse`, `DelRecordQuery`, `FetchOptions`, `FileInfo`, `Form`, `ForwardRequestStreamOptions`, `GetRecordQuery`, `Index`, `Newsletter`, `ProgressCallback`, `PostRecordsItem`, `PostRecordsResult`, `UploadFilesResult`, `FileUploadError`, `RealtimeCallback`, `RecordData`, `RequestHistory`, `RTCConnector`, `RTCConnectorParams`, `RTCEvent`, `RTCReceiverParams`, `RTCResolved`, `StreamChunk`, `StreamPollResult`, `Subscription`, `Table`, `Tag`, `UniqueId`, `UserAttributes`, `UserProfile`, `UserPublic`, `WebSocketMessage` # Getting Started Skapi is a serverless backend API for web applications. To build a full-stack web application, create a project and connect it to your HTML or JavaScript code. If an AI coding agent writes that code for you, set the agent up right after creating the project; it takes care of the rest. ## Creating a Project 1. Sign up at [skapi.com](https://www.skapi.com) if you do not have an account yet. 2. Log in and [Create a new Project](https://www.skapi.com/new-project). If you are not signed in, the page sends you to log in first and brings you back to the project form once you are in. 3. Give your project a name, an optional description and a region, and click **Continue**. 4. Choose a plan and proceed. An account that already has projects can also click **+ New Project** on its project list. Your new project opens on its `Settings` page. The **Information** card holds the **Project ID**, the value every example in this documentation calls ``. Click it to copy it. ![The Settings page of a Skapi project: the Project card with its name and description, the Information card with the Project ID, Owner ID, Service ID, Region, creation date and a link to the documentation, and the Application Examples card below](https://docs.skapi.com/screenshots/settings-page.webp) *The Settings page of a project. The Project ID is on the Information card.* The same page has two shortcuts worth knowing from day one: **Application Examples** opens ready-made HTML pages that already run against your project (see [Full Examples](#doc-full-example-intro)), and **For AI Agents** downloads the base prompt for your AI coding tool (see [Setting up AI Agents](#doc-introduction-getting-started-setting-up-ai-agents) below). :::tip For BunnyQuery users [BunnyQuery](https://www.bunnyquery.com) projects are fully compatible with Skapi. Your project will appear in both your BunnyQuery and Skapi project lists. ::: If you write the code yourself, continue with [Working on the Codebase](#doc-introduction-codebase). If an AI coding agent writes it, set the agent up first. ## Setting up AI Agents Skapi works smoothly with AI coding tools, such as Claude Code, Codex CLI, Gemini CLI, GitHub Copilot, Cursor and Windsurf. There are two ways an AI agent can help you build on Skapi, and they work well together: - A **base prompt** in your project teaches the agent how to write code against the Skapi API. - The **Skapi MCP server** lets the agent work on your project itself: your database, your settings, your tickets, your secret keys and more, signed in as you. ### Download the base prompt for your tool Every tool reads the same file under its own name. Pick your tool, and the file downloads with the name it expects. Put it in the root of your project. - Claude Code: save it as `CLAUDE.md` - Codex CLI / OpenCode: save it as `AGENTS.md` - Gemini CLI: save it as `GEMINI.md` - GitHub Copilot: save it as `copilot-instructions.md` - Cursor: save it as `.cursorrules` - Windsurf: save it as `.windsurfrules` Browsers drop the leading dot from a download name, so `.cursorrules` and `.windsurfrules` are saved as `cursorrules` and `windsurfrules`. Add the dot back after saving. You can also download the plain SKAPI.md and rename it yourself. The file is small on purpose, about 25 KB: the rules, a map of this documentation and an index of every SDK method, each linking to its page. The agent reads a page when it builds the feature, from `https://docs.skapi.com/md/` (every page of this site is there as raw markdown, at the same path), so a session carries only the pages it needs. If your agent cannot fetch urls, allow it access to `docs.skapi.com`, or connect the [Skapi MCP server](#doc-introduction-getting-started-connecting-the-skapi-mcp-server): its `readDocs` tool returns the same pages. A tool that indexes one document can take the whole documentation as a single file, [SKAPI-full.md](https://docs.skapi.com/SKAPI-full.md); it is too large to paste into a chat. Your project's `Settings` page at [skapi.com](https://www.skapi.com) offers the same downloads under **For AI Agents**, next to the opening prompt with your project ID already filled in. Click **[Download]** on the row of your tool, and click the prompt to copy it. ![The For AI Agents card on a project's Settings page: the opening prompt with the project ID filled in, and one Download row per tool, from Claude Code to Windsurf](https://docs.skapi.com/screenshots/settings-agents.webp) *The For AI Agents card on the Settings page. The file is the same for every tool; only its name differs.* ### Start writing prompts When you run your AI coding agent, start with a prompt like this: ```text My Skapi project ID is: "". Build me a [describe what you want]. ``` Replace the placeholder `` with your actual project ID before running your prompt. The Project ID is on the **Information** card of your project's `Settings` page (see [Creating a Project](#doc-introduction-getting-started-creating-a-project)). ## Connecting the Skapi MCP server **Connecting the MCP server is optional.** The base prompt above is all an agent needs to write your application's code, and your application never talks to the MCP server. What the server adds is the **administrative side** of a project, the work you would otherwise do by hand on the Skapi dashboard: it connects the agent to your Skapi projects, signed in as you, so it can register the tickets and secret keys an integration needs, set up OpenID sign-in, change the project's settings, publish the website, read and fix records, and manage the project's users, from invitations to access groups. Each of those becomes a sentence in a prompt instead of a form. Skip this section if you only want help writing code, and come back when a feature needs something set up on the project. 1. Add this MCP endpoint to your AI platform: **https://mcp.broadwayinc.computer** 2. Choose OAuth. No client ID or client secret is needed. 3. Sign in with your Skapi account when the platform asks. The server answers nothing until you have signed in, so a platform that lists it as needing authentication is waiting for that sign-in; see [Signing in](#doc-introduction-getting-started-signing-in). Any platform that speaks MCP works. The endpoint is the same everywhere; only the place you put it differs. ### Coding agents Each of these opens your browser to sign you in with your Skapi account the first time the agent uses the server. Leave any client ID or client secret field empty. ::: code-group ```sh [Claude Code] claude mcp add --transport http skapi https://mcp.broadwayinc.computer ``` ```sh [Codex CLI] codex mcp add skapi --url https://mcp.broadwayinc.computer codex mcp login skapi ``` ```sh [Gemini CLI] gemini mcp add --transport http skapi https://mcp.broadwayinc.computer ``` ```json [Cursor] { "mcpServers": { "skapi": { "url": "https://mcp.broadwayinc.computer" } } } ``` ```json [VS Code / Copilot] { "servers": { "skapi": { "type": "http", "url": "https://mcp.broadwayinc.computer" } } } ``` ```json [Windsurf] { "mcpServers": { "skapi": { "serverUrl": "https://mcp.broadwayinc.computer" } } } ``` ::: | Platform | Where it goes | Signing in | | --- | --- | --- | | Claude Code | The command above. Add `--scope user` to have the server in every project. | `claude mcp list` shows the server as **Needs authentication** until you sign in. Run `claude mcp login skapi`, or `/mcp` in a session, pick **skapi** and choose **Authenticate**. | | Codex CLI | The command above writes `[mcp_servers.skapi]` with `url` into `~/.codex/config.toml`. | `codex mcp login skapi` | | Gemini CLI | The command above writes `httpUrl` into `.gemini/settings.json`. Add `-s user` to have the server in every project. | Automatic. `/mcp auth skapi` in a session starts it again. | | Cursor | `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project. The Customize page manages the same list. | Prompted in the browser | | VS Code with GitHub Copilot | `.vscode/mcp.json`, or Command Palette, **MCP: Add Server**. | Prompted in the browser on first connection | | Windsurf, now Devin Desktop | `~/.config/devin/mcp_config.json`, opened from the MCPs entry of the Cascade panel's menu. The Devin CLI also takes `devin mcp add skapi https://mcp.broadwayinc.computer`. | Prompted in the browser, or `devin mcp login skapi` | ### Chat platforms on the web A web platform has no command line, so the server is added in its settings instead, usually on a page called Connectors, Integrations, Apps or MCP servers. Look for an option to add a custom or remote server, paste the endpoint, leave the client ID and secret empty, and sign in when it asks. - **Claude** (claude.ai, the desktop app and Cowork): **Customize > Connectors**, then **Add custom connector**. Paste the endpoint and click **Add**. On Team and Enterprise plans an organization owner adds it under **Organization settings > Connectors**, and every member clicks **Connect**. - **ChatGPT**: turn on **Developer mode** under **Settings > Security and login**, open **chatgpt.com/plugins**, click **+**, give it a name and paste the endpoint as the connection. In a chat, choose **Developer mode** from the **+** menu and pick it. Available on the paid plans. Other platforms follow the same pattern. Zed, JetBrains AI Assistant, Cline, Kiro and Amp all take a remote MCP server by URL from their settings page or their config file. Wherever a platform asks for a transport, choose **Streamable HTTP**; wherever it asks how to authenticate, choose **OAuth**. Then tell the agent which project to work on: ```text Use my Skapi project "". ``` You can also ask it to list your projects and pick one. If you have no project yet, the agent will tell you so and give you the link to the project form on [skapi.com](https://www.skapi.com/new-project); the MCP server does not create projects. ### Signing in The server signs you in with OAuth, using your Skapi account. Your platform registers itself with the server and proves each sign-in with PKCE, so there is no client ID or client secret to enter anywhere. - **Nothing works before you sign in.** The server refuses every request that carries no sign-in, the first connection included. That refusal is what makes a platform open the sign-in page, and until you finish it the platform shows the server as needing authentication and the agent sees none of its tools. - **The sign-in renews itself.** The platform refreshes it in the background while you use it. If the agent has not used the server for about 30 days, the platform asks you to sign in again. - **The agent acts as you.** It reaches only the projects and data your account can reach; see [What the MCP server can do for you](#doc-introduction-getting-started-what-the-mcp-server-can-do-for-you). If a tool answers **Unauthorized**, or the platform reports an incompatible authorization server, it is holding a connection made before the current sign-in. Sign in again: in Claude Code run `claude mcp login skapi`, elsewhere use the platform's reconnect or authenticate option, or remove the server and add it again. ### Signing in without a browser The sign-in above opens a browser. On a machine that has none, over SSH, in a container or in continuous integration, or on a platform that only takes a fixed header, there are two ways in. **A command-line sign-in that prints a link.** Claude Code and Codex CLI can sign in without opening a browser themselves: ```sh claude mcp login skapi --no-browser codex mcp login skapi ``` Each prints a URL. Open it on any device where you can sign in to Skapi, finish, and paste the address it returns back into the terminal. Claude Code needs a real terminal for this, so over SSH connect with `ssh -t`. **An access token you set as a header.** For anything else, including a script, a scheduled job, or a platform that offers only a header field, use an access token. The MCP server has a page that issues them: **https://mcp.broadwayinc.computer/connect** Open it in any browser (`https://www.skapi.com/mcp` is a shortcut to the same page). It runs the same Skapi sign-in a platform would open, then lets you create tokens. The steps: 1. Open the page and sign in with your Skapi account. 2. Click **Create token**, and optionally label it so you can tell your machines apart. 3. Copy the token. It starts with `skmcp_` and is shown once, right then, never again. 4. Give it to your platform as the `Authorization: Bearer` header. For Claude Code: ```sh claude mcp add --transport http skapi https://mcp.broadwayinc.computer \ --header "Authorization: Bearer skmcp_YOUR_TOKEN" ``` In a config file the token goes in a `headers` entry (`"Authorization": "Bearer skmcp_YOUR_TOKEN"`) on the server, or, for Codex CLI, in `bearer_token_env_var`. The `/connect` page prints the whole entry for Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code and Windsurf. The token acts as you, with everything your account can reach, for as long as that sign-in lasts or until you revoke it. Return to the same page any time to see your tokens and revoke one. A platform set up with a token never opens the sign-in page; when you revoke the token it reports the server as unauthorized until you give it a new one. Keep the token as secret as a password. ### What the MCP server can do for you Everything below runs with the permissions of the signed-in account, so the agent can only reach what you can, and every change it makes is one you could have made on the dashboard yourself. Your Skapi account, the project owner, gets all of it. An admin of the project (a user in access group `90` ~ `99`) who signs in through the server gets the user management tools, under the same rules the app applies to admins; see [Admin Permissions](#doc-admin-permissions). - **Users.** Search the project's users, and manage their accounts the way the dashboard's Users page does: send, resend, cancel and list invitations, create accounts, grant access groups, update profiles, and block, unblock or delete accounts. The agent asks before it blocks or deletes. An invitation is an e-mail and counts as one of the project's monthly e-mail sends, resends included; see [Inviting Users](#doc-admin-invite) and [Managing Users](#doc-admin-account). - **Tickets.** Register the endpoints that accept a webhook from your payment provider, a link, or a signed-in request, with their conditions, placeholders, actions and error handling, and read their logs afterwards. See [Registering a Ticket](#doc-tickets-introduction). - **Secret keys.** Store the API keys of the third-party services your project calls, so your front end never holds them, and limit the URLs each key may be sent to. See [Secret Keys](#doc-api-bridge-client-secret-request). - **OpenID loggers.** Set up sign-in through an external identity provider, including the profile request, the header it needs and a condition on who may sign in, such as one e-mail domain. See [OpenID Login](#doc-authentication-openid-login). - **Database.** Read, search, create, update and delete records. List tables, tags, indexes and unique IDs, and find any of them by how its name starts or ends. It can also read the files attached to a record and give you a download link for them, but it cannot attach a file to a record or remove one: a record sent with files to attach or remove is refused and not saved, while the other records in the same request are still saved. Attach and remove a record's files in the Skapi dashboard (Database page) or with the SDK. Deleting a record still deletes the files attached to it, as it does everywhere else. - **Project settings.** Turn sign-ups or inquiries on and off, restrict anonymous writes, and change the other settings of the project. - **Hosting.** Register a web address, then upload, edit and delete the files of your project's website. - **E-mails** (project owner only). Compose an automated e-mail template, of any type, or a newsletter, and upload it as e-mail HTML or as plain text, with the same checks the dashboard makes (e-mail HTML, the type's required placeholders, the size). An uploaded template is added to its list and is never put in use by the agent; an uploaded newsletter is saved without sending. The owner chooses the template, or sends the newsletter, on the dashboard, or a ticket's Send e-mail or Send newsletter action names it. See [Uploading a template](#doc-email-email-templates-uploading-a-template) and [Uploading a newsletter](#doc-email-newsletters-uploading-a-newsletter). The ticket, secret key and OpenID logger pages of this documentation each show the dashboard forms these tools fill in for you. A few prompts to start with: ```text Save this API key as a secret named "weather_api", usable only for https://api.weather.example: . Create a ticket that saves each incoming webhook payload to the "orders" table, readable by admins only. Register a Google OpenID logger for this project, and let in only addresses that end with "@mycompany.com". Show me what my "orders" ticket received today. Make every record in the "posts" table private. Write a welcome e-mail for my shop, in my brand's tone, and upload it as the welcome template. Compose this month's newsletter about the new autumn menu and save it to the public list without sending it. ``` The agent picks the tools, asks when something is missing, and reports what it changed. When a project is at a limit of its plan (users, monthly e-mail sends, newsletter subscribers, storage or bandwidth), the agent is told which limit, and is given the link to the project's plan page, where the project owner upgrades. The server itself never changes a plan, and never creates or deletes a project; see [Plans and Limits](#doc-introduction-plans). With the project created and the agent set up, the rest happens in your code: continue with [Working on the Codebase](#doc-introduction-codebase). # Working on the Codebase Whether you write the code yourself or an AI coding agent writes it for you, this is the part that lives in your codebase: load the Skapi library, create one instance connected to your project, and build on it. Every other page of this documentation calls methods on the `skapi` instance created here. You need the **Project ID** of your project. It is on the project's `Settings` page, under **Information** (see [Creating a Project](#doc-introduction-getting-started-creating-a-project)). An AI agent takes it from your opening prompt (see [Setting up AI Agents](#doc-introduction-getting-started-setting-up-ai-agents)). ## Initializing Skapi ### For HTML Projects For a vanilla HTML project, load Skapi with a script tag and initialize the library as shown below. Add the Skapi script and initialize the `Skapi` class in the `` of each page that uses Skapi. Use your Skapi project's exact Project ID when initializing the library. ```html ``` :::warning Replace the placeholder `` is a placeholder, including the angle brackets. Replace the entire placeholder with your actual Project ID from the Skapi dashboard. For example: ```js const skapi = new Skapi("abc123defg456hij78-9klmnop012qrstu345vwxyz"); ``` Every example in this documentation uses the same `""` placeholder. Replace it wherever you copy an example. ::: The Project ID uniquely identifies your Skapi project. ### For SPA Projects To use Skapi in a single-page application (SPA) such as Vue, React, or Angular, install `skapi-js` with npm. ```sh $ npm i skapi-js@2.2.5 ``` Then import the library in your main JavaScript file: ```javascript // main.js import { Skapi } from "skapi-js"; const skapi = new Skapi(""); export { skapi } // You can now import skapi from anywhere in your project. ``` ### For TypeScript Projects Skapi includes TypeScript support, so you can import the `Skapi` class and related types. ```typescript import { Skapi } from 'skapi-js'; import type { RecordData, DatabaseResponse } from 'skapi-js'; const skapi = new Skapi(""); let databaseRecords: DatabaseResponse; ``` For lists of types, refer [Data Types](#doc-api-reference-data-types). ### Node.js (CommonJS) To use Skapi in Node.js (CommonJS), import the library as shown below: ```javascript const { Skapi } = require('skapi-js'); const skapi = new Skapi(""); ``` ### Node.js (ESM) ```javascript import { Skapi } from 'skapi-js'; const skapi = new Skapi(""); ``` > **Note:** When running Skapi in Node.js, browser-specific features such as WebSocket, WebRTC, and Notifications are unavailable. ## Get Connection Information After your client connects to Skapi, call [`getConnectionInfo()`](#doc-api-reference-connection-getconnectioninfo) to retrieve information about the connection. ::: code-group ```html [HTML] ``` ```javascript [SPA] import { skapi } from '../location/of/your/main.js'; skapi.getConnectionInfo().then(info => { console.log(info); /* Returns: { project_id: "Public ID of the connected project", user_ip: "Connected user's IP address", user_agent: "Connected user's user agent", user_location: "Connected user's country code", service_name: "Your project name", service_description: "Your project description", version: 'x.x.x', // Skapi library version ai_agent: "AI agent instructions configured for the project", conf: { freeze_database: boolean, // The database is read-only prevent_signup: boolean, // Sign-up is blocked prevent_inquiry: boolean, // Inquiries are blocked prevent_anonymous: boolean // Anonymous users cannot write to the database } } */ window.alert(`Connected to ${info.service_name}`); }); ``` ::: ## Advanced Settings You can pass additional options when initializing the `Skapi` class. ### new Skapi(...) ```ts class Skapi { constructor( project_id: string, // Skapi project ID. options?: { autoLogin?: boolean; // Default: true refetchServiceInfo?: boolean;// Default: false. Bypasses cached project information and fetches fresh information on every load. requestBatchSize?: number; // Default: 50. Maximum number of requests processed per batch. encryption?: boolean | { // Default: false. Encrypts private record data in the browser. Can only be set during initialization. HTTPS is required. iterations?: number; // Default: 600000. PBKDF2 cost. Minimum: 100000. minPasswordLength?: number; // Default: 0 (off). Rejects passwords shorter than this value. persistDevice?: boolean; // Default: true. Keeps encryption unlocked across page reloads on that device. recovery?: 'code' | 'none'; // Default: 'code'. Issues a one-time recovery code. trustPolicy?: 'tofu' | 'strict'; // Default: 'tofu'. Controls how a recipient's public key is trusted when sharing. withheld?: 'null' | 'sentinel'; // Default: 'null'. Specifies what `data` contains when a record cannot be decrypted. table?: string; // Default: '__skapi__keyring'. Reserved table for the user's keyring. }; eventListener?: { onLogin?: (user: UserProfile | null) => void; // Fires on initial page load (after Skapi initializes), on login/logout, and when a session expires. The callback receives a UserProfile object if the user is logged in; otherwise, it receives null. onUserUpdate?: (user: UserProfile | null) => void; // Fires on initial page load (after Skapi initializes), on login/logout, when a session expires, and when the user's profile is updated. The callback receives a UserProfile object if the user is logged in; otherwise, it receives null. onBatchProcess?: (process: { batchToProcess: number; // Number of batches remaining itemsToProcess: number; // Number of items remaining completed: any[]; // Results completed in this batch }) => void; } }) { ... } ... } ``` Options overview: - `autoLogin` (boolean, default: true) - Automatically restores the user's session when the page loads. - See: [Auto Login](#doc-authentication-login-logout-auto-login) - `requestBatchSize` (number, default: 50) - Maximum number of requests processed in each batch. - `encryption` (boolean | object, default: false) - Encrypts the `data` of records saved with `access_group: 'private'` in the browser before the data reaches the database. The contents of files attached to those records are encrypted as well. - **This option takes effect only when it is set during `Skapi` initialization.** There is no method for enabling encryption later. If this option is omitted, the instance saves every record's `data` as plain text for its entire lifetime. - Enabling encryption later does not encrypt records that were already saved as plain text. - Setting it to `true` uses the default settings. Pass an object to customize them: - `iterations` (number, default: 600000): PBKDF2 cost for deriving the key from the user's password. Minimum: 100000. - `minPasswordLength` (number, default: 0, off): rejects passwords shorter than this value. Because encryption strength is limited by the user's password, setting a minimum is recommended. - `persistDevice` (boolean, default: true): keeps encryption unlocked across page reloads on that device. - `recovery` ('code' | 'none', default: 'code'): issues a one-time recovery code. This is the only way to regain access to the data after a password reset. - `trustPolicy` ('tofu' | 'strict', default: 'tofu'): controls how a recipient's public key is trusted when a record is shared. `'strict'` requires the key to be pinned before the first share. - `withheld` ('null' | 'sentinel', default: 'null'): specifies what `data` contains when a record cannot be decrypted. `'sentinel'` returns a placeholder object with the reason instead of `null`. - `table` (string, default: '__skapi__keyring'): the reserved table for the user's keyring. - See: [Encrypting Private Record Data](#doc-database-encryption) - `eventListener` (callbacks for key events) - `onLogin(user: UserProfile | null)` - Fires after Skapi initializes on the initial page load, after login or logout, and when a session expires. The callback receives a `UserProfile` object when the user is logged in; otherwise, it receives `null`. - See: [Listening to Login/Logout Status](#doc-authentication-login-logout-listening-to-login-logout-status) - `onUserUpdate(user: UserProfile | null)` - Fires after login, before logout, when a session expires, and when the user's profile is updated. The callback receives a `UserProfile` object when the user is logged in; otherwise, it receives `null`. - See: [Listening to User Profile Updates](#doc-authentication-user-info-listening-to-user-s-profile-updates) - `onBatchProcess(process)` - Fires each time Skapi finishes processing a request batch. Type reference: See [UserProfile](#doc-api-reference-data-types-userprofile). # Working with HTML Forms Skapi can handle HTML `onsubmit` events directly by passing the `SubmitEvent` as the first argument to Skapi methods. This makes form handling much simpler. You can process and send form data without manually reading each field. In this example, we use [`skapi.mock()`](#doc-api-reference-connection-mock) to send a request and receive a response. Here is an example of using a `
` with Skapi: ```html
``` This is equivalent to writing the following code manually: ```html ``` When a form submit event is passed as the first argument to a Skapi method, Skapi automatically converts form input values into JavaScript key-value data. The input `name` becomes the key, and the value is resolved based on the input type. ## Nested Values and Arrays You can create nested values and arrays by using the `[]` syntax in the `name` attribute. The resolved data structure will depend on the input type. If the key inside `[]` is a number, Skapi resolves the value as an array. ```html
Skills: JavaScript Python IDE: Vim Emacs Check:
``` The above example will resolve to the following structure: ```ts { user: { name: string, age?: number, skills?: "JavaScript" | "Python", ide?: "Vim" | "Emacs" | <"Vim" | "Emacs">[] }, check: boolean[] } ``` Skapi automatically structures user input based on input type and the `name` attribute. Number inputs are resolved as numbers, radio inputs are resolved as the selected value, and checkbox inputs are resolved as boolean values or strings if a value is specified. When multiple inputs share the same name without `[]`, Skapi attempts to convert the values into an array. ## Using Input Elements, Textarea, and Select Elements Skapi also works with individual input elements, including text, number, radio, checkbox, textarea, and select elements. ```html ``` In this example, we use the `id` attribute to reference the input element and pass it directly to a Skapi method. This approach is useful when you want to handle a single field instead of a full form. ## Using the `action` Attribute in the `
` Element When you set a URL in a form's `action` attribute, the user is redirected to that page after a successful request. On the destination page, use [`skapi.getFormResponse()`](#doc-api-reference-connection-getformresponse) to retrieve the resolved data from the previous page. The example below shows how to submit a form in `index.html` and read the resolved data in `welcome.html`. For this example, create these two HTML files in the same directory. ``` . ├─ index.html └─ welcome.html ``` :::code-group ```html [index.html]
``` ```html [welcome.html]

Welcome

Your message:

``` ::: ::: tip When building a static website, you can use the `action` attribute to redirect users to a new page after a successful request. Each page should have the Skapi library imported and initialized. In a single-page application, redirecting to another page is often unnecessary. ::: # Signing Up Users To let users create a new account in your project, you can use the [`signup()`](#doc-api-reference-authentication-signup) method. ### Example: Signing Up Users ::: code-group ```html [Form]

Sign-Up

``` ```js [JS] let parameters = { email: "user@email.com", password: "password", // Password must be between 6 and 60 characters. name: "User's name" }; skapi.signup(parameters) .then(res => window.location.href = 'login.html') .catch(err => window.alert(err.message)); ``` ::: The example above shows how to let users create their account in your project. Once the user signup is successful, the user will be redirected to the login page. The first argument takes the user's input (email, password, name) that will be used for signup. ::: warning - If the user have not logged in to your project after account creation, they will **NOT** appear on your user list in Skapi's admin page. - If 7 days have passed since the account creation, and the user still have not logged in to your project, user's signup will be automatically invalidated. ::: ## Login after Signup The second argument takes additional options when creating an account. You can also automatically login the user right after successful signup by setting `options.login` to `true` in options argument. With `options.email_subscription` the user is subscribed to a newsletter once they confirm their e-mail: `0` or `'public'` for the public newsletter, `1` or `'authorized'` for Service Email, or the name of a named newsletter group. It requires `signup_confirmation`. See [Subscribing at signup](#doc-email-newsletters-subscribing-at-signup). ::: code-group ```html [Form]
``` ```js [JS] let parameters = { email: "user@email.com", password: "password", // Password must be between 6 and 60 characters. name: "User's name" }; let options = { login: true // If set to true, users will be automatically logged in after signup. }; skapi.signup(parameters, options) .then(u => alert('Hello ' + u.name)); ``` ::: When the `options.login` is set to `true`, the method will return the [UserProfile](#doc-api-reference-data-types-userprofile) object. For more detailed information on all the parameters and options available with the [`signup()`](#doc-api-reference-authentication-signup) method, please refer to the API Reference below: ### [`signup(params, options?): Promise`](#doc-api-reference-authentication-signup) `options` also takes a `template` argument, which lets a single `signup()` call use a specific uploaded template for the signup confirmation and welcome e-mails instead of the template set for your project. For more info, see [Overriding the template for a single call](#doc-email-email-templates-overriding-the-template-for-a-single-call). ### E-Mail and username `email` is always required. Every account needs one, because it is what signup confirmation, e-mail verification, password reset and account recovery all work through. An account cannot be created without it. `username` is optional, and when you pass one the account gets **two** ways in. The username becomes the account's permanent login ID, and once the email is verified it logs the account in as well. Leave `username` out and the email alone is the login ID, which is what most projects want. The username is permanent. It is fixed when the account is created and there is no API to change it. The email is not, but changing it does not hand email login to the new address on its own. The new address logs the account in only once the user verifies it with [`verifyEmail()`](#doc-api-reference-user-verifyemail), and it starts working a few seconds after the verification succeeds, not in the `verifyEmail()` response. An email an admin changes with [`updateUserAttributes()`](#doc-api-reference-admin-updateuserattributes) is written unverified and takes the account's email login away at once, until the user verifies the new address. The username is unaffected either way, and so is the address the account signed up with when it was created without a `username`: that original address is the account's own login ID, not an email login, and it keeps working after an email change. See [Which ID logs a user in](#doc-user-account-update-account-which-id-logs-a-user-in). ```js skapi.signup({ email: 'user@email.com', password: 'password', username: 'my_username' }) .then(() => { // The username logs the account in from the moment it is created. skapi.login({ username: 'my_username', password: 'password' }); // The email logs the same account in once it is verified, and not before. skapi.login({ email: 'user@email.com', password: 'password' }); }); ``` The email keeps every other job it had: it is still the address verification and password-reset e-mails go to, and it is still what `email_public` exposes. For an account created with a `username`, email login starts once that email is **verified**, never before. An email only proves the account owns it once one of these happens: - the user clicks the confirmation link, when `signup_confirmation` is used, - the user accepts the invitation, for an account made with [`inviteUser()`](#doc-api-reference-admin-inviteuser), - the user calls [`verifyEmail()`](#doc-api-reference-user-verifyemail) and it succeeds, which is what a `signup()` without `signup_confirmation` and an account made with [`createAccount()`](#doc-api-reference-admin-createaccount) need. Creating the account proves nothing about the address, so it logs in with its username alone until the user verifies. Email login then arrives a few seconds later, on the account's next token, rather than in the `verifyEmail()` response. Until then the email does not reach the account at all, even while the invitation or the confirmation link is pending. A user who types their email before opening the confirmation link gets `INCORRECT_USERNAME_OR_PASSWORD`, not `SIGNUP_CONFIRMATION_NEEDED`, and that attempt does not let [`resendSignupConfirmation()`](#doc-api-reference-authentication-resendsignupconfirmation) send the link again. A login attempt with the username does both. If that email is already a login ID another account of your project was **granted**, email login is not enabled for the new account, and the username still logs it in. `signup()` creates such an account anyway; `createAccount()` and `inviteUser()` refuse it up front with `EXISTS` (see below). ### When a login ID is already taken A login ID can only ever lead to one account. So an account is refused when its own login ID is already a login ID another account of your project was **granted**: the ID that account was created with, or an address it has verified. The usual case is signing up without a `username` with the verified email of an account that was created with one: ```js // 'user@email.com' is the email of an account that was created with a username. skapi.signup({ email: 'user@email.com', password: 'password' }) .catch(err => { // err.code: 'EXISTS' // err.message: 'E-mail "user@email.com" is already a login ID in this service.' }); ``` `signup()` refuses a `username` the same way, with the message `The login ID is already used by another account in this service.`, when that `username` is an address another account was granted as its email login. Only an e-mail address can be one, for example a `username` of `jane@email.com` when `jane@email.com` is the verified email of an account created with a username. A login ID that another account was itself created with (the same `username`, or the same email both times without a `username`) is a plain duplicate and gives `The account already exists.` instead. `createAccount()` and `inviteUser()` run this check for every request without `openid_id`, with or without a `username`, and they also refuse an account created with a `username` whose email is already a login ID another account was granted, including the email that account was created with. See the `EXISTS` errors of [`inviteUser()`](#doc-api-reference-admin-inviteuser) and [`createAccount()`](#doc-api-reference-admin-createaccount). :::warning Your permanent login ID is never taken away The account's permanent login ID is fixed: - if the account was created with a username, that username is the permanent login ID; - if the account was created without a username, the original email is the permanent login ID. That permanent login ID stays with the account and is never reassigned to another account. What can be taken away is a separate email login that is not the account's permanent login ID. If another account proves it owns the same email and verifies it, that separate email login can be reassigned to the other account. See [Login IDs](#doc-admin-permissions-login-ids). ::: # Signup Confirmation You can require users to confirm their signup via email. This is useful for preventing malicious users from creating fake accounts. The account is not fully activated until the user confirms it. ## E-Mail Confirmation on Signup When an account is created with `options.signup_confirmation` set to `true` or a URL string, the user receives a signup confirmation email. The user must click on the confirmation link before logging into your project. If the `options.signup_confirmation` value is a valid URL string, the user is redirected to that URL after successful confirmation. You can use either a full URL or a relative path on your website. Once the user has confirmed their signup, their profile will automatically be marked as email verified. For an account created with a `username`, that is also what gives its email address a login: from then on the username and the email both log the account in. See [E-Mail and username](#doc-authentication-create-account-e-mail-and-username). :::code-group ```html [Form]
``` ```js [JS] let parameters = { email: "user@email.com", password: "password", name: "User's name" }; let options = { /** * If set to true, the user will get a signup confirmation email with a confirmation link. * If set to a valid URL string, the user will be redirected to the url when the confirmation is successful. */ signup_confirmation: '/path/to/your/success/page' }; skapi.signup(parameters, options).then(res => { // "SUCCESS: The account has been created. User's signup confirmation is required." console.log(res); }); ``` ::: The example above shows how to create an account with signup confirmation enabled. After signup succeeds, the user receives an email with a confirmation link. After they click the link, the account is confirmed and the user is redirected to the URL you provided. If the `signup_confirmation` value was `true`, the user sees a blank browser tab with the message: 'Your signup has been successfully confirmed.' :::danger When setting the `signup_confirmation` value to a relative URL path (e.g. `/relative/path.html`), it will not work if the website is not hosted. This happens because local files use paths like `file:///C:/Users/username/Desktop/website/index.html`, and Skapi cannot resolve folder paths on a user's local computer. Set your redirect URL of `signup_confirmation` to be the full URL (e.g. `https://your.website.com/path/to/your/success/page`). ::: You can also customize the signup confirmation email template. For more info on email templates, see [Automated E-Mail](#doc-email-email-templates). ## Resending Signup Confirmation E-Mail If you need to resend the confirmation email, use the [`resendSignupConfirmation()`](#doc-api-reference-authentication-resendsignupconfirmation) method. :::code-group ```html [Form]
``` ```js [JS] skapi.login({email: 'user@email.com', password: 'password'}) .then(u=>console.log('Successfully logged in.')) .catch(err=>{ /** * { * code: 'SIGNUP_CONFIRMATION_NEEDED', * message: "User's signup confirmation is required.", * name: 'SkapiError' * } */ if(err.code === 'SIGNUP_CONFIRMATION_NEEDED') { let sendConfirmation = window.confirm('Your signup confirmation is required. Resend confirmation email?'); if(sendConfirmation) { // now you can resend signup confirmation E-Mail to user@email.com. skapi.resendSignupConfirmation().then(res=>{ console.log(res); // 'SUCCESS: Signup confirmation e-mail has been sent.' }); } } else throw err; }); ``` ::: In this example, the user tries to log in and receives a `SIGNUP_CONFIRMATION_NEEDED` error. If needed, you can then call [`resendSignupConfirmation()`](#doc-api-reference-authentication-resendsignupconfirmation) to resend the confirmation email. For detailed information about all parameters and options of [`resendSignupConfirmation()`](#doc-api-reference-authentication-resendsignupconfirmation), see the API reference below: ### [`resendSignupConfirmation(): Promise<'SUCCESS: Signup confirmation e-mail has been sent.'>`](#doc-api-reference-authentication-resendsignupconfirmation) ::: warning - To resend signup confirmation emails, the user must have at least one login attempt to your project. - If the user does not confirm within 7 days, the signup is invalidated and they must sign up again. ::: # Login / Logout Once a user has signed up, they can log in to your project using their email and password. ## Login Use the [`login()`](#doc-api-reference-authentication-login) method to log a user into your project. If the login is not successful due to invalid password, or user may not have confirm their signup etc... the [`login()`](#doc-api-reference-authentication-login) method will throw an error. When successful, it will respond with the [`UserProfile`](#doc-api-reference-data-types-userprofile) object. :::warning If `signup_confirmation` option was set to `true` during [`signup()`](#doc-api-reference-authentication-signup), users will not be able to log in until they have confirmed their account. ::: :::info When the user has successfully confirmed their signup and logged in, they will be sent a welcome email. You can also customize the email template for the signup confirmation email. For more info on email templates, see [Automated E-Mail](#doc-email-email-templates). ::: Below is an example of a login form that uses the [`login()`](#doc-api-reference-authentication-login) method. When the user successfully logs in, they will be redirected to the `welcome.html` page. ::: code-group ```html [Form]

Login





``` ```js [JS] let parameters = { email: "user@email.com", password: "password", }; skapi.login(parameters).then((user) => (window.location.href = "welcome.html")); ``` ::: For more detailed information on all the parameters and options available with the [`login()`](#doc-api-reference-authentication-login) method, please refer to the API Reference below: ### [`login(params): Promise`](#doc-api-reference-authentication-login) If the account was created with a `username`, the username logs the user in from the moment the account is created, and the account's current email does too once that address is **verified**. Pass whichever the user typed. Until the address is verified, by the signup confirmation link, by accepting an invitation or by [`verifyEmail()`](#doc-api-reference-user-verifyemail), only the username reaches the account, and the email answers `INCORRECT_USERNAME_OR_PASSWORD`. Email login then starts a few seconds after the verification, on the account's next token. An account created **without** a `username` logs in with the address it signed up with, which is its own permanent login ID and keeps working even after the email is changed. See [E-Mail and username](#doc-authentication-create-account-e-mail-and-username) for when email login starts, and the one case where it is not enabled. ## Auto Login By default, once user login to your website, their login session is maintained until they logout. To ensure that users' sessions are destroyed when they leave your website, you can set options.autoLogin to false in the third argument when initializing Skapi. ```javascript const options = { autoLogin: false, // session is destroyed when the user leaves; omit or set true (the default) to keep the session. }; //Set the third argument as options const skapi = new Skapi("", options); ``` ## Logout The [`logout()`](#doc-api-reference-authentication-logout) method logs the user out from the project. :::code-group ```html [Form]
``` ```js [JS] skapi.logout().then((res) => { console.log(res); // 'SUCCESS: The user has been logged out.' window.location.replace("page_to_show_after_logout.html"); }); ``` ::: ## Global Logout You can let the users logout and invalidate all tokens across all the users devices by setting `params.global` to `true`. :::code-group ```html [Form]
``` ```js [JS] skapi.logout({ global: true }).then((res) => { console.log(res); // 'SUCCESS: The user has been logged out.' window.location.replace("page_to_show_after_logout.html"); }); ``` ::: For more detailed information on all the parameters and options available with the [`logout()`](#doc-api-reference-authentication-logout) method, please refer to the API Reference below: ### [`logout(params?): Promise<'SUCCESS: The user has been logged out.'>`](#doc-api-reference-authentication-logout) ## Listening to Login / Logout Status You can listen to the updates of the user's login state by setting a callback function in the `option.eventListener.onLogin` option argument of the constructor argument in Skapi. The `onLogin` callback is triggered in the following cases: - Skapi initializes with the user's current authentication state. - User logs in or logs out. - User loses their session due to an expired token. If the user is logged in, the callback receives the [UserProfile](#doc-api-reference-data-types-userprofile) object; otherwise, it receives `null`. ```js const options = { eventListener: { onLogin: (profile) => { console.log(profile); // is null when user is logged out, User's information object when logged in. }, }, }; const skapi = new Skapi("", options); ``` You can also add multiple event listeners to the `onLogin` event after the Skapi object has been initialized. ```js skapi.onLogin = (profile) => { console.log(profile); // null when user is logged out, User's information object when logged in. }; ``` This handler is useful for updating the UI when the user logs in, logs out. # User Profile Once a user has logged in, they can retrieve their profile information. The profile data is structured as an OpenID-compliant JavaScript object. ## Requesting User Information The [`getProfile()`](#doc-api-reference-authentication-getprofile) method allows you to retrieve the user's information via promise method. It returns the [UserProfile](#doc-api-reference-data-types-userprofile) object. If the user is not logged in, [`getProfile()`](#doc-api-reference-authentication-getprofile) returns `null`. This method is particularly useful for determining the user's authentication state when they first visit or reload your website. ```js skapi.getProfile().then(profile=>{ console.log(profile); // User's information if(profile === null) { // The user is not logged in } }) ``` You can also refresh the auth token and fetch the updated profile by passing `options.refreshToken` to `true`. ```js skapi.getProfile({ refreshToken: true }).then(profile=>{ console.log(profile); // Updated user's information if(profile === null) { // The user is not logged in } }) ``` This can be useful when the user needs to get their updated profile when it's updated from another device, or admin might have made change to the users profile, or you just want your users to update their token for some other security reasons. For more detailed information on all the parameters and options available with the [`getProfile()`](#doc-api-reference-authentication-getprofile) method, please refer to the API Reference below: ### [`getProfile(options?): Promise`](#doc-api-reference-authentication-getprofile) ## Listening to User's Profile Updates You can listen to the updates of the user profiles by setting a callback function in the `option.eventListener.onUserUpdate` option argument of the constructor argument in Skapi. The `onUserUpdate` callback function will be triggered in the following scenarios: - Skapi initializes with the user's current authentication state. - User logs in or logs out. - User loses their session due to an expired token. - User's profile information is updated. If the user is logged in, the callback receives the [UserProfile](#doc-api-reference-data-types-userprofile) object; otherwise, it receives `null`. ```js const options = { eventListener: { onUserUpdate: (profile) => { console.log(profile); // is null when user is logged out, User's information object when logged in. } } }; const skapi = new Skapi("", options); ``` You can also add multiple event listeners to the `onUserUpdate` event after the Skapi object has been initialized. ```js skapi.onUserUpdate = (profile) => { console.log(profile); // null when user is logged out, User's information object when logged in. } ``` This handler is useful for updating the UI when the user logs in, logs out, or when their profile information changes. # Forgot password When the user forgets their password, they can request a verification code to reset their password. :::warning If the user's email is not verified, they will not be able to receive a verification code and may lose access to their account permanently. It is recommended to encourage users to verify their email addresses. For more info on email verification, see [E-Mail Verification](#doc-user-account-email-verification). ::: ## Step 1: Request Verification Code Use the [`forgotPassword()`](#doc-api-reference-authentication-forgotpassword) method to request a verification code. In this example, the [`forgotPassword()`](#doc-api-reference-authentication-forgotpassword) method is called with the user's email as a parameter. The user will receive an email containing a verification code that they can use to reset their password. :::code-group ```html [Form]
``` ```js [JS] skapi.forgotPassword({email: 'someone@gmail.com'}).then(res=>{ // User receives an e-mail with a verification code. // SUCCESS: Verification code has been sent. console.log(res); }); ``` ::: For more detailed information on all the parameters and options available with the [`forgotPassword()`](#doc-api-reference-authentication-forgotpassword) method, please refer to the API Reference below: ### [`forgotPassword(params, options?): Promise<'SUCCESS: Verification code has been sent.'>`](#doc-api-reference-authentication-forgotpassword) ::: info Due to security reasons, [`forgotPassword()`](#doc-api-reference-authentication-forgotpassword) will not tell the user whether the email exists. ::: You can also customize the email template for the verification email. For more info on email templates, see [E-Mail Templates](#doc-email-email-templates). To use a different template for one call instead of the one set for your project, pass its `message_id` in the optional `options.template` argument. For more info, see [Overriding the template for a single call](#doc-email-email-templates-overriding-the-template-for-a-single-call). ## Step 2: Reset Password The user will receive an email containing a verification code. After the user receives the verification code, they can use the [`resetPassword()`](#doc-api-reference-authentication-resetpassword) method to reset their password. The [`resetPassword()`](#doc-api-reference-authentication-resetpassword) method is called with the user's email, the verification code received via email, and the new password. Upon successful password reset, the user's account password will be set to the new password provided. :::code-group ```html [Form]
``` ```js [JS] skapi.resetPassword({ email: 'someone@gmail.com', code: '123456', // code sent to user's registered email address new_password: 'new_password' // The password should be at least 6 characters and 60 characters maximum. }).then(res => { console.log(res); // SUCCESS: New password has been set. }); ``` ::: For more detailed information on all the parameters and options available with the [`resetPassword()`](#doc-api-reference-authentication-resetpassword) method, please refer to the API Reference below: ### [`resetPassword(params): Promise<'SUCCESS: New password has been set.'>`](#doc-api-reference-authentication-resetpassword) # OpenID Login Skapi supports OpenID authentication through configurable OpenID Loggers. ## What is OpenID? OpenID is an authentication standard that lets users sign in with an identity provider (for example, Google) instead of creating a separate password for every app. ## Login with OpenID Profile If you have access to an OpenID provider API, you can register an OpenID Logger in your Skapi project settings. :::warning An OpenID Logger is a project setting Registering, updating, deleting and listing OpenID Loggers belong to the **project owner's Skapi account**, and to Skapi staff when you ask Skapi for help. An [admin](#doc-admin-permissions-project-settings-belong-to-the-project-owner) of your project, access group `99` included, is refused with `INVALID_REQUEST` and `Only the project owner can change project settings.` The same holds for the [Secret Keys](#doc-api-bridge-client-secret-request-registering-secret-keys) a logger uses. ::: Although providers differ in details, the overall process is: 1. You redirect the user to the provider's login page. 2. The provider authenticates the user. 3. The user is redirected back to your app. 4. Exchange the returned authorization code for an access token with [`forwardRequest()`](#doc-api-bridge-forward-request) and a stored Secret Key. 5. Call [`openIdLogin()`](#doc-api-reference-authentication-openidlogin) with the token. ## Google OAuth Example This example shows how to implement Google OAuth authentication. ### 1. Set Up Google OAuth Service Go to the [Google Cloud Console](https://console.cloud.google.com/) and create your OAuth app. Follow Google's [setup instructions](https://support.google.com/cloud/answer/15549257?sjid=3416534526948669406-NC), and make sure your redirect URL points back to your web app. ### 2. Set Up Link to Google Login After setting up OAuth in [Google Cloud Console](https://console.cloud.google.com/), create a button that sends users to Google's OAuth login URL with the parameters registered for your app. ```html ``` ### 3. Register a Secret Key After a successful Google login, the user is redirected back to your page with a `code` query parameter. You must exchange this `code` for an access token. Because this step requires a client secret, store the secret in Skapi and request the token with [`forwardRequest()`](#doc-api-bridge-forward-request). To register a secret key in Skapi: 1. In the project page, click on the **Secret Keys** menu. 2. Click **+ Register Secret**. 3. In the form, enter: - **Name:** A key identifier. For this guide, use **ggltoken**. - **Secret Value:** The exact client secret from your Google OAuth app. 4. Click **Register**. For more information about registering a secret key, see [Secret Keys](#doc-api-bridge-client-secret-request-registering-secret-keys). After registering the client secret, run the following code on the redirect page to exchange the authorization code for an access token: ```js // Page user has redirected to const GOOGLE_CLIENT_ID = '1234567890123-your.google.client.id'; const REDIRECT_URL = window.location.origin + window.location.pathname; const urlParams = new URLSearchParams(window.location.search); const code = urlParams.get('code'); const tokenResponse = await skapi.forwardRequest({ code, client_id: GOOGLE_CLIENT_ID, client_secret: '$CLIENT_SECRET', redirect_uri: REDIRECT_URL, grant_type: 'authorization_code' }, { secretName: 'ggltoken', url: 'https://oauth2.googleapis.com/token', method: 'POST', headers: { 'Content-Type': 'application/json' } }); const ACCESS_TOKEN = tokenResponse?.access_token; ``` ### 4. Register Your OpenID Logger in Skapi To log users into your Skapi project with the token, you must register an OpenID Logger. The logger configuration tells Skapi how to request user profile attributes from the OAuth provider and which attribute to use as the unique account identifier. 1. Log in to [skapi.com](https://www.skapi.com) and open the project. 2. From the side menu, click **Open ID**. The page lists the loggers the project has, with their Logger ID, Username Key, Request URL and Method. ![The Open ID page of a Skapi project, listing two loggers with their Logger ID, Username Key, Request URL and Method, and a Register Logger button](https://docs.skapi.com/screenshots/openid-list.webp) *The Open ID page. Click a row to open a logger. Tick rows and use the delete icon to remove them.* 3. Click **+ Register Logger**. 4. Fill in the form: - **Logger ID:** The name your app passes to [`openIdLogin()`](#doc-api-reference-authentication-openidlogin). You can use any name, and it cannot change later. For this guide, use **google**. - **Username Key:** The attribute of the provider's profile response that becomes the user's unique username. It cannot change later. For this example, use **email**. - **Request URL:** The endpoint that returns the user's profile. `$TOKEN` in the URL is replaced by the OpenID token at sign-in. For this example, use `https://www.googleapis.com/oauth2/v3/userinfo`. - **Method:** `GET` or `POST`, as the API requires. For this example, use `GET`. - **Header [JSON]:** Request headers as JSON. `$TOKEN` is replaced here too. Use: ``` { "Authorization": "Bearer $TOKEN" } ``` - **Get Parameters [JSON]** or **Post Body [JSON]:** Query parameters for `GET`, or the request body for `POST`, as JSON. Leave it blank for this example. - **Condition:** Optional. Only users whose profile attribute meets the condition can sign in through this logger. **Attribute** is the profile attribute to compare, **Condition** is the comparison, and **Value** is what it is compared with. On text, `>=` means the attribute **starts with** the value and `<=` means it **ends with** it, so `email` `<=` `@mycompany.com` lets in only that e-mail domain. Leave them blank for this example. ![The Register Logger form filled in for Google: Logger ID google, Username Key email, the userinfo Request URL, Method GET, an Authorization header in the Header JSON field, and an empty Condition section](https://docs.skapi.com/screenshots/openid-register.webp) *The logger form filled in for this example.* 5. Click **Register**. To change a logger later, click its row on the **Open ID** page, edit the request fields and click **Update**. The Logger ID and the Username Key are fixed once registered. **Delete** at the bottom of the form removes the logger, and users who signed in through it lose access to the project. :::tip Let an AI agent do it The Skapi MCP server can register, update and delete OpenID loggers for you from an AI agent, along with the secret key the token exchange uses. See [Connecting the Skapi MCP server](#doc-introduction-getting-started-connecting-the-skapi-mcp-server). ::: Now call [`openIdLogin()`](#doc-api-reference-authentication-openidlogin) with the logger ID and the access token to sign in (or create) the user. In this example, the logger ID is `google`. ```js skapi.openIdLogin({ id: 'google', token: ACCESS_TOKEN }).then(user => { // User has logged in! }); ``` ### [`openIdLogin(event?: SubmitEvent | params): Promise<{ userProfile: UserProfile; openid: { [attribute: string]: string } }>`](#doc-api-reference-authentication-openidlogin) ### Wrapping up: All in one page This example shows the entire flow in one page. After the user signs in with Google and is redirected back to your app, use [`forwardRequest()`](#doc-api-bridge-forward-request) to exchange the authorization code for an access token. Then call [`openIdLogin(event?: SubmitEvent | params): Promise<{ userProfile: UserProfile; openid: { [attribute: string]: string } }>`](#doc-api-reference-authentication-openidlogin) to sign the user in to your Skapi project. ```html ``` ## Merging an OpenID Account with a Previous Account In some cases, you may want to merge a user's OpenID account with an existing account. Accounts created by admins are merged like any other account that matches (see below which accounts match): an account made with [`createAccount()`](#doc-api-reference-admin-createaccount), or an invited account once its invitation is accepted. A matching account that is still waiting for its signup confirmation, or whose invitation has not been accepted yet, cannot be merged: `openIdLogin()` fails with `INVALID_REQUEST` and `The account needs to be confirmed.`, with or without `merge`. To enable merging, set your OpenID Logger ID to `by_skapi`. Then, when calling `openIdLogin`, use the `merge` option to control what gets merged. Set `merge: true` to merge the OpenID account into the existing account (its password is replaced and no profile attributes are copied), or pass an array of OpenID attribute names, such as `["name"]`, to merge and also copy those attributes. For example, to merge and also copy the user's "name" attribute: ```js skapi.openIdLogin({ id: 'by_skapi', token: ACCESS_TOKEN, merge: ["name"] }); ``` :::danger After a merge, the user can no longer log in with a password. This action cannot be undone. ::: Merge only matches the account whose original login identifier is the OpenID account's login ID, for example an account created without a `username` using the same email. It never matches an account through its email login: an account created with a `username` that uses the same email, or an account whose email was changed to that address later, is not merged into. What happens to such an account depends on whether it has **verified** that address. If it has, the email login is one it was granted, and `openIdLogin()` fails with `EXISTS` and `The login ID of this OpenID account is already used by another account.`, with or without `merge`. If it has not, that email login is removed and a new OpenID account is created for the address, so two accounts of your project then carry the same email address. See [`openIdLogin()`](#doc-api-reference-authentication-openidlogin) and [Login IDs](#doc-admin-permissions-login-ids). :::tip You can first attempt login without the `merge` parameter and only prompt the user to merge if the account already exists: ```js skapi.openIdLogin({ id: 'by_skapi', token: ACCESS_TOKEN }) .catch(err => { if (err.code === 'ACCOUNT_EXISTS') { if (confirm('An account already exists. Merge them now?')) { return skapi.openIdLogin({ id: 'by_skapi', token: ACCESS_TOKEN, merge: true }); } } throw err; // Re-throw if not handled }); ``` ::: # Updating User Profile :::warning You must be logged in to call this method. ::: You can update a user's profile using [`updateProfile()`](#doc-api-reference-user-updateprofile). If successful, the method returns the updated [UserProfile](#doc-api-reference-data-types-userprofile) object. :::danger - When the email is changed, it becomes unverified. - Changing the email does **not** hand email login to the new address. The new address logs the account in only once the user verifies it with [`verifyEmail()`](#doc-api-reference-user-verifyemail), and then a few seconds later, on the account's next token rather than in the `verifyEmail()` response. - The old address stops logging the account in on that same next token. A `username`, if the account has one, is permanent and is not affected, and neither is the address a no-username account was created with. See [Which ID logs a user in](#doc-user-account-update-account-which-id-logs-a-user-in) below. ::: In this example, the user's name is updated by passing a new `name` value. If successful, the updated user profile is returned. :::code-group ```html [Form]

``` ```js [JS] let params = { name: "New name", // email, // The user's login email address. The email will be unverified if it is changed. // address, // The user's address. // gender, // The user's gender. Can be "female" or "male", or other values if neither of these are applicable. // birthdate, // The user's birthdate in the format "YYYY-MM-DD". // phone_number, // The user's phone number. // email_public, // The user's email is public if this is set to true. The email should be verified. // phone_number_public, // The user's phone number is public if this is set to true. The phone number should be verified. // address_public, // The user's address is public if this is set to true. // gender_public, // The user's gender is public if this is set to true. // birthdate_public, // The user's birthdate is public if this is set to true. // picture, // URL of the profile picture. // profile, // URL of the profile page. // website, // URL of the website. // nickname, // Nickname of the user. // misc, // Additional string value for custom use. This value is visible only through skapi.getProfile(). }; skapi.updateProfile(params).then((user) => { console.log({ user }); // User's name is updated. }); ``` ::: For full details on parameters and options, see the API reference below: ### [`updateProfile(params): Promise`](#doc-api-reference-user-updateprofile) :::tip If you need to upload an image to a user's profile, first upload a public image file with [`postRecord()`](#doc-api-reference-database-postrecord), then use the uploaded file URL in the profile attributes. ::: ## Public Attributes Certain user profile attributes can be set as public or private. When an attribute is public, other users can find it. When an attribute is private, other users cannot find it. The following attributes can be set to public or private: - `email` - `phone_number` - `address` - `gender` - `birthdate` By default, these attributes are set to private. Here is an example that makes the user's email public: :::code-group ```html [Form]
Make email public
``` ```js [JS] let params = { email_public: true, }; skapi.updateProfile(params).then((user) => { console.log({ user }); // User's email is now public. }); ``` ::: For full details on parameters and options, see the API reference below: ### [`updateProfile(params): Promise`](#doc-api-reference-user-updateprofile) ## Which ID logs a user in An account has **one or two** ways in: - The **login ID it was created with**: its `username` when it was created with one, otherwise the email address it signed up with. It is permanent, no method changes it, and it keeps working after the account changes its email. - Its **email login**: the account's current email address, and only once that address is **verified**. **Account created with a username.** The username is the permanent login ID and never changes. The current email logs the user in too, once it is verified. Change the email and the account is left with its username alone: the old address stops working on the next token, and the new one starts working a few seconds after [`verifyEmail()`](#doc-api-reference-user-verifyemail) succeeds. **Account created without a username.** The address the account signed up with keeps working as a login ID forever, even after the email is changed, because that original address is what identifies the account internally. A changed address is an email login on top of it, so it works only once it is verified, and it stops working when the email is changed again. So if you need an address to stop being a way in, give the account a `username` at creation. Only then does the original address lose its hold. An email address proves the account owns it when the user clicks the signup confirmation link, accepts an invitation, or calls `verifyEmail()` successfully. Until then it does not reach the account at all, and it answers `INCORRECT_USERNAME_OR_PASSWORD`. If the address is already a login ID another account of the project was granted, email login is not enabled and the account's own login ID still works. See [E-Mail and username](#doc-authentication-create-account-e-mail-and-username) and [Login IDs](#doc-admin-permissions-login-ids). :::warning An admin changing the email takes email login away at once An email an admin sets with [`updateUserAttributes()`](#doc-api-reference-admin-updateuserattributes), or with `updateProfile()` and another user's `user_id`, is written unverified and the account's email login is removed inside that request, whoever sent it. The account keeps its own login ID, and gets an email login back only after the user verifies the new address. ::: # E-Mail Verification :::warning User must be logged in to call this method ::: User with verified E-Mail can: - Log in with their email address, when the account was created with a `username`. See [Which ID logs a user in](#doc-user-account-update-account-which-id-logs-a-user-in). - Reset their password if they've forgotten it. - Receive newsletter from the project owner if they choose to. - Recover their disabled account. - Allow their email address to be public to other users if they choose. You can verify your user's email address with [`verifyEmail()`](#doc-api-reference-user-verifyemail). :::tip The user's email is automatically verified if [signup confirmation](#doc-authentication-signup-confirmation) was requested in [`signup()`](#doc-api-reference-authentication-signup). ::: The example below shows how you can verify your users email address. 1. The first method call, without any arguments, sends a verification email to the user. 2. The second call completes the verification process by passing the verification code that user retrieved from their email. ``` js // Send verification code to user's E-Mail skapi.verifyEmail().then(res=>{ // 'SUCCESS: Verification code has been sent.' console.log(res); // Prompt user to enter the verification code let code = prompt('Enter the verification code sent to your E-Mail'); // Verify E-Mail with the code skapi.verifyEmail({ code }).then(res=>{ // SUCCESS: "email" is verified. window.alert('Your email is verified'); }); }); ``` For more detailed information on all the parameters and options available with the [`verifyEmail()`](#doc-api-reference-user-verifyemail) method, please refer to the API Reference below: ### [`verifyEmail(params?, options?): Promise<'SUCCESS: Verification code has been sent.' | 'SUCCESS: "email" is verified.'>`](#doc-api-reference-user-verifyemail) :::warning The user's email verified state will be lost if the user had changed their email address, or if an admin changed it for them. Email login goes with it: the account logs in with its `username`, or with the address it was created with when it has none, until the new address is verified. Verifying it grants the email login again a few seconds later, on the account's next token. See [Login IDs](#doc-admin-permissions-login-ids). ::: `options` takes a `template` argument, which lets a single call use a specific uploaded template for the verification e-mail instead of the template set for your project. It applies to the call that issues a new code, and is ignored when you pass a code back to verify it. For more info, see [Overriding the template for a single call](#doc-email-email-templates-overriding-the-template-for-a-single-call). # Changing Password :::warning User must be logged in to call this method. ::: The [`changePassword()`](#doc-api-reference-user-changepassword) method allows users who are logged-in to change their password. This method requires the user's current password and the new password as parameters. If the password change is successful, the method will return a success message. Password should be at least 6 characters and no more than 60 characters. :::code-group ```html [Form]
``` ``` js [JS] let params = { current_password: 'current password', new_password: 'new password' } skapi.changePassword(params) .then(res => { alert(res); // SUCCESS: Password has been changed. }); ``` ::: For more detailed information on all the parameters and options available with the [`changePassword()`](#doc-api-reference-user-changepassword) method, please refer to the API Reference below: ### [`changePassword(params): Promise<'SUCCESS: Password has been changed.'>`](#doc-api-reference-user-changepassword) # Disable / Recover Account ## Disabling account :::warning User must be logged in to call this method ::: :::warning If your project does not allow users to signup, the users will not be able to disable their account. For more information on how to allow/disallow users to signup from your project settings page, please refer to the [Project Settings](https://docs.skapi.com/service-settings/service-settings.html#allow-signup) page. ::: If user choose to leave your project, they can disable their account. User's can disable their account by calling the [`disableAccount()`](#doc-api-reference-user-disableaccount) method. **All data related to the account will be deleted after 90 days**. User will be automatically logged out once their account has been disabled. ``` js skapi.disableAccount().then(()=>{ // Account is disabled and user is logged out. }); ``` For more detailed information on all the parameters and options available with the [`disableAccount()`](#doc-api-reference-user-disableaccount) method, please refer to the API Reference below: ### [`disableAccount(): Promise<'SUCCESS: account has been disabled.'>`](#doc-api-reference-user-disableaccount) ## Recovering a Disabled Account Disabled accounts can be reactivated **within 90 days** using the [`recoverAccount()`](#doc-api-reference-user-recoveraccount) method. This method allows users to reactivate their disabled accounts under the following conditions: - The account email must be verified. - The [`recoverAccount()`](#doc-api-reference-user-recoveraccount) method must be called from the `catch` block of a failed [`login()`](#doc-api-reference-authentication-login) attempt using the disabled account. The [`recoverAccount()`](#doc-api-reference-user-recoveraccount) method sends an email to the account owner, containing a confirmation link (The same signup confirmation email) for account recovery. Additionally, you can provide an optional `string` argument to the [`recoverAccount()`](#doc-api-reference-user-recoveraccount) method, which will redirect the user to the specified URL or relative path of your website upon successful account recovery. :::code-group ```html [Form]
``` ```js [JS] // user attempt to login skapi.login({email: 'user@email.com', password: 'password'}) .then(u=>console.log('Login success.')) .catch(err=>{ console.log(err.code); // USER_IS_DISABLED if(err.code === 'USER_IS_DISABLED') { // Send a recovery email to the user with a link. // When the user click on the link, the user will be redirected when account recovery is successful. let recover = window.confirm('Do you want to recover your account?') if(recover) { skapi.recoverAccount("/welcome/back/page").then(res=>{ console.log(res); // SUCCESS: Recovery e-mail has been sent. }); } } }); ``` ::: In the example above, the [`recoverAccount()`](#doc-api-reference-user-recoveraccount) method is called from the catch block of a failed login attempt using a disabled account. If the login attempt fails with the error code `"USER_IS_DISABLED"`, user can choose to recover their account. The [`recoverAccount()`](#doc-api-reference-user-recoveraccount) method is called to send a recovery email to the user. The recovery email contains a link, and when the user clicks on the link, they will be redirected to the relative path of the website URL: `/welcome/back/page` upon successful account recovery. For more detailed information on all the parameters and options available with the [`recoverAccount()`](#doc-api-reference-user-recoveraccount) method, please refer to the API Reference below: ### [`recoverAccount(redirect: boolean | string): Promise<'SUCCESS: Recovery e-mail has been sent.'>`](#doc-api-reference-user-recoveraccount) :::danger User should know their password, and have their account email verified. Otherwise user's account cannot be recovered. ::: # Searching Users :::warning User must be logged in to call this method ::: Users can search, retrieve information of other users in your project using the [`getUsers()`](#doc-api-reference-user-getusers) method. By default, [`getUsers()`](#doc-api-reference-user-getusers) will return all users chronologically from the most recent sign-up. User information retrieved from the database is returned as a list of [UserPublic](#doc-api-reference-data-types-userpublic) objects. :::info Any attribute that is not set to public will not be retrieved. ::: ```js skapi.getUsers().then(u=>{ console.log(u.list); // List of all users in your project, sorted by most recent sign-up date. }); ``` In the example above, the [`getUsers()`](#doc-api-reference-user-getusers) method is called without any parameters. This retrieves a list of all user profiles in your project. For more detailed information on all the parameters and options available with the [`getUsers()`](#doc-api-reference-user-getusers) method, please refer to the API Reference below: ### [`getUsers(params?, fetchOptions?): Promise>`](#doc-api-reference-user-getusers) ## Searching users with conditions Following examples shows how you can search users based on attributes such as name, timestamp (account created timestamp), birthdate... etc #### Search for users whose name starts with 'Baksa' ```js let params = { searchFor: 'name', condition: '>=', // >= means greater or equal to given value. But on string value, it works as 'starts with' condition. value: 'Baksa' } skapi.getUsers(params).then(u=>{ console.log(u.list); // List of users whose name starts with 'Baksa' }); ``` #### Search for users who joined before 2023 Jan 1 ```js let timestampParams = { searchFor: 'timestamp', condition: '<', // Less than given value value: 1672498800000 //2023 Jan 1 } skapi.getUsers(timestampParams).then(u=>{ console.log(u.list); // List of users who joined before 2023 jan 1 }); ``` #### Search for users whose birthday is between 1985 ~ 1990 ```js let birthdateParams = { searchFor: 'birthdate', value: '1985-01-01', range: '1990-12-31' // Queries range of value from given value to given range value. } skapi.getUsers(birthdateParams).then(u=>{ console.log(u.list); // List of users whose birthday is between 1985 ~ 1990 }); ``` #### Search for a single user whose `user_id` falls in a range ```js let userIdParams = { searchFor: 'user_id', value: '00000000-0000-0000-0000-000000000000', range: 'ffffffff-ffff-ffff-ffff-ffffffffffff' } skapi.getUsers(userIdParams).then(u=>{ console.log(u.list); // List of users whose user_id falls between the value and range }); ``` #### Fetch multiple users by their `user_id` ```js let multipleIdParams = { searchFor: 'user_id', value: [ '00000000-0000-0000-0000-000000000000', '11111111-1111-1111-1111-111111111111' ] // condition defaults to '=', and each id is looked up directly. This is not a range search. } skapi.getUsers(multipleIdParams).then(u=>{ console.log(u.list); // The users matching either id, if they exist }); ``` #### Fetch multiple users by a list of e-mails ```js let multipleEmailParams = { searchFor: 'email', value: ['alice@example.com', 'bob@example.com'] // condition defaults to '=', and each e-mail is looked up directly. This is not a range search. } skapi.getUsers(multipleEmailParams).then(u=>{ console.log(u.list); // The users matching either e-mail, if they exist and are public }); ``` The `searchFor` parameter specifies the attribute to search for, and the value parameter specifies the search value. :::info - Passing a `value` array (fetching several known values at once, e.g. several `user_id`s or `email`s) only works with the default `=` condition and does not accept `range`, whichever attribute you search for. It looks up each value directly instead of running a range query. - Users cannot search for attributes that are not set to public. ::: #### The following attributes can be used in `searchFor` to search for users: - `user_id`: unique user identifier, string - `email`: user's email address, string - `phone_number`: user's phone number, string - `name`: user's profile name, string - `address`: user's physical address, string - `gender`: user's gender, string - `birthdate`: user's birthdate in "YYYY-MM-DD" format, string - `locale`: the user's locale, a string representing the country code (e.g "US" for United States). - `subscribers`: number of subscribers the user has, number - `timestamp`: timestamp of user's sign-up, number(13 digit unix time) - `approved`: search by account approval status #### The `condition` parameter allows you to set the search condition. - `>`: Greater than the given value. - `>=`: Greater or equal to the given value. When the value is `string`, it works as 'starts with' condition. - `=`: Equal to the given value. (default) - `<`: Lesser than the given value. - `<=`: Lesser or equal to the given value. On `email`, `phone_number`, `name`, `address`, `gender` and `locale`, it works as 'ends with' instead. When searching for a `string` attribute, `>` and `<` will search for strings that are higher or lower in the lexicographical order, respectively. And `>=` operator works as 'start with' condition. #### Search for users whose e-mail ends with '@company.com' ```js let endsWithParams = { searchFor: 'email', condition: '<=', value: '@company.com' } skapi.getUsers(endsWithParams).then(u=>{ console.log(u.list); // List of users whose e-mail ends with '@company.com' }); ``` :::info `email`, `phone_number`, `name`, `address`, `gender` and `locale` are the only attributes that support the 'ends with' (`<=`) condition. It is served from a separate reverse-index that skapi keeps in sync with your user data, so it is as fast as any other condition search. ::: :::tip What an admin sees Admins (access groups `90` ~ `99`) and the project owner get more from the same call: the `email` of every account, whether or not the user made it public, its `email_verified` state, and the `misc` field, which is otherwise visible only to the account itself. `searchFor: 'email'` searches those addresses too, so an admin can find an account by an address that is not public. Everything else follows the rules above. See [What an admin can see about a user](#doc-admin-permissions-what-an-admin-can-see-about-a-user). ::: The `range` parameter enables searching for users based on a specific attribute value within a given range. For example, if searching by `timestamp` with a range of 1651748526 to 1651143726, only users created between the two timestamps will be returned. :::warning The `range` parameter cannot be used with the `condition` parameter. ::: # Creating a Record Use [`postRecord()`](#doc-api-reference-database-postrecord) to create a new record or update an existing record in the database. This method takes two arguments: - `data`: The content to save as key-value pairs. This can be an object literal, `null`, `undefined`, or a form `SubmitEvent`. After upload, the value is stored under the `data` key in the returned [RecordData](#doc-api-reference-data-types-recorddata). - `config` (required): Upload configuration, including table name, access group, index values, and more. See the example below: :::code-group ```html [Form]
``` ```js [JS] // Data to be saved in key:value pairs let data = { something: "Hello World" } // Configuration for the record to be uploaded let config = { table: { name: 'my_collection', access_group: 'public' } } skapi.postRecord(data, config).then(rec=>{ console.log(rec); /* Returns: { data: { something: "Hello World" }, table: { name: 'my_collection', access_group: 'public' }, ... } */ }); ``` ::: This example demonstrates using the [`postRecord()`](#doc-api-reference-database-postrecord) method to create a record in the database. When successful, the method returns [RecordData](#doc-api-reference-data-types-recorddata). In this example, the first argument is the data to upload. The value of `something` is saved as part of the record and appears under the `data` key in the returned [RecordData](#doc-api-reference-data-types-recorddata). In the second argument, the table name is set to `my_collection` and the access group is set to `public`. `config.table` is required. Every record must include a table name. You can think of the table name as the top-level category for your data. Later, you can fetch records by table. `config.table.name` validation rules: - Maximum length: 128 characters - Must not be empty - Must not include control characters or sentinel `􏿿` If the access group is `public`, anyone can access the uploaded data. To use different access restrictions, see [`Access Restrictions`](#doc-database-access-restrictions). ::: danger Both authenticated and anonymous users can upload data to your project with [`postRecord()`](#doc-api-reference-database-postrecord). Limitations for anonymous (unsigned) users: 1. They can only create records in the `public` access group (see [`Access Restrictions`](#doc-database-access-restrictions)). 2. They cannot edit or delete any records they create. 3. They cannot create records that use [`Subscription`](#doc-database-subscription) features. 4. They cannot create records with [`Unique ID`](#doc-database-unique-id) features. You can prevent anonymous uploads by changing your project settings in the Skapi dashboard. ::: ::: warning When an anonymous user uploads a record, the `user_id` value in the returned [`RecordData`](#doc-api-reference-data-types-recorddata) is temporary and should not be used for user queries. ::: For more detailed information on all the parameters and options available with the [`postRecord()`](#doc-api-reference-database-postrecord) method, please refer to the API Reference below: ### [`postRecord(data, config):Promise`](#doc-api-reference-database-postrecord) :::tip Note Skapi does not require you to predefine a database schema. If the specified table does not exist, it will be automatically created when you create the record. Conversely, if a table has no records, it will be automatically deleted. ::: ## Creating Several Records at Once [`postRecords()`](#doc-api-reference-database-postrecords) takes a list of `{ data, config }` items, each the two arguments of [`postRecord()`](#doc-api-reference-database-postrecord), and saves them 100 to a request. Use it when a page writes many records in one go, such as one record per imported row or per uploaded file: a thousand records are ten requests instead of a thousand. ```js let result = await skapi.postRecords( rows.map(row => ({ data: row, config: { table: { name: 'imports', access_group: 'public' } } })) ); // result { list: [RecordData], // the records that were saved, in the order given failed: [ // the items that were not, each by its position in the list { index: 7, code: 'INVALID_PARAMETER', message: '...' } ] } ``` An item that is refused does not stop the others: it is reported in `failed` with its `index`, and the same `code` and `message` `postRecord()` would have rejected with, while the items after it are still saved. `list.length + failed.length` is always the number of items given. Only a failure of a request itself (the connection, the sign-in, a server error) rejects the call, and the records saved before it stay saved. Every item follows the rules of `postRecord()`: the same `config` keys, the same table naming rules, the same access checks. Two differences: `data` is an object (or null), not a form with files, and files are not attached here. Attach them to a saved record with [`uploadFiles()`](#doc-database-handling-files-uploading-files-to-an-existing-record), which with many files asks for its upload permits in batches as well. ### [`postRecords(items):Promise`](#doc-api-reference-database-postrecords) ## Large Record Data There is no separate call for a large payload. When a record's `data` is larger than 32 KB, Skapi stores the value as a file in your project's file storage instead of keeping it in the database, and the record keeps only a reference to it. The value then counts toward your file storage instead of your database storage, see [Plans and Limits](#doc-introduction-plans-large-record-data). Reading it back needs nothing from you either. The SDK fetches the value and puts it in `record.data`, so what you get is what you posted, whatever its size. The file it lives in never appears in the record's `bin`, and it cannot be uploaded or deleted by name: `"__data__/__json__.json"` is a reserved file name in [`postRecord()`](#doc-api-reference-database-postrecord) and in [`deleteFiles()`](#doc-api-reference-database-deletefiles). # Fetching Records The [`getRecords()`](#doc-api-reference-database-getrecords) method allows you to fetch records from the database. It retrieves records based on the specified query parameters and returns a promise that resolves to the [DatabaseResponse](#doc-api-reference-data-types-databaseresponse) containing the [RecordData](#doc-api-reference-data-types-recorddata) object. It takes two arguments: - `query`: Specifies the query parameters for fetching records. - `fetchOptions`: (optional) Specifies additional configuration options for fetching database records For more information, see [Database Fetch Options](#doc-database-fetch-database-fetch-options). ### Fetching Records from a Table ```js let query = { table: { name: 'my_collection', access_group: 'public' } } skapi.getRecords(query).then(response=>{ // response /** * endOfList: true, * list: [ * ... * ], * startKey: 'end', * ... */ }); ``` The example above retrieve records from a table named 'my_collection' with `access_group` that are `public` The `table` parameter in the `query` argument sets the table name you want to fetch records from. The retrieved records are accessed through the `response.list` property. When fetching the records with access restrictions, see [`Access Restrictions`](#doc-database-access-restrictions). For more detailed information on all the parameters and options available with the [`getRecords()`](#doc-api-reference-database-getrecords) method, please refer to the API Reference below: ### [`getRecords(query, fetchOptions?): Promise>`](#doc-api-reference-database-getrecords) ### Fetching Record by ID You can fetch a record by its unique ID using the [`getRecords()`](#doc-api-reference-database-getrecords) method. When fetching a record by ID, you don't need to provide any additional configuration parameters. ```js let query = { record_id: 'record_id_to_fetch' }; skapi.getRecords(query).then(response => { // response /** * endOfList: true, * list: [{ * ... // only 1 result * }], * startKey: 'end' // startKey is 'end' as no more records can be retrieved */ }); ``` In this example, the `query` object includes the `record_id` property set to the ID of the record you want to fetch. `record_id` is a unique identifier for each record in the database. The `response.list` will contain the record data if the record exists. ## Database Fetch Options [FetchOptions](#doc-api-reference-data-types-fetchoptions) can control the number of the record per fetch, fetching the next batch of records, fetching the records by ascending/descending order... etc. This is used globally for all database related methods that allows optional [FetchOptions](#doc-api-reference-data-types-fetchoptions) argument. See full list of parameters: [FetchOptions](#doc-api-reference-data-types-fetchoptions) #### Limit Results with `fetchOptions.limit` By default, 50 sets of the data will be fetched per call. You can adjust the limit to your preference, allowing up to **1000 sets of data**, by using the `limit` key. #### Fetch More Results with `fetchOptions.fetchMore` To fetch the next batch of results, you can set the `fetchOption.fetchMore` to `true`. When set to `false`(default), database will always return the first batch of the data. This allows you to retrieve results in batches until the end of the list is reached. #### Order results with `fetchOptions.ascending` By default, the database fetch the data in ascending order. If set to `false`, list of data can be fetched in descending order For example, let's say there is millions of record in the database table 'my_collection'. We can fetch the first 100 data, then paginate to the next 100 data by setting `fetchOptions.fetchMore` to `true`. ``` js let query = { table: { name: 'my_collection', access_group: 'public' } } let fetchOptions = { limit: 100, // Limit each fetch to 100 data. fetchMore: false, // When false, database always gives you the first batch of data. ascending: false // Fetch in decending order. } skapi.getRecords(query, fetchOptions).then(res=>{ console.log(res.list); // List of up to 100 data in the database. if(!res.endOfList) { // If there is more data to fetch, and if user chooses to, they can retrieve the next batch of 100. fetchOptions.fetchMore = true; if(confirm('Fetch more records?')) { skapi.getRecords(query, fetchOptions) .then(res=>{ console.log(res.list); // List of the next 100 data from the database. } ); } } }); ``` In this example, after the first call to the database, we see the `endOfList` value is not `true`. This means there are more data left to fetch in the database. To fetch more data in the database, we set `fetchOptions.fetchMore` to `true` and call the method again. This allows to fetch the next batch of 100 data on each execution until the end of the list is reached. :::tip When using the `fetchMore` parameter, you must check if the response's `endOfList` value is `true` before making the next call. The database will always return an empty list if the `fetchOptions.fetchMore` is set to `true` and it had reached the end of list and. You can however, initialize your fetch and refetch from start by toggling `fetchOptions.fetchMore` back to `false`. ::: :::tip You can fetch all the data at once by recursively calling the method until the `endOfList` value is `true`. However for efficiency, avoid trying to fetch all the data at once. Fetch only data the user needs and paginate when necessary. ::: # Table Information Skapi tracks all tables in your database. Use [`getTables()`](#doc-api-reference-database-gettables) to retrieve table names, record counts, and table sizes. You can fetch the full table list like this: ```js skapi.getTables().then(response => { console.log(response); // List of all tables in the database }); ``` Called with no argument, or with an empty query object, [`getTables()`](#doc-api-reference-database-gettables) returns **every** table in the project. That is how you list everything: give no `table`, and give no `condition`. ### Who can read table information When the project's [Require Login](https://docs.skapi.com/service-settings/service-settings.html#require-login) setting is on, [`getTables()`](#doc-api-reference-database-gettables) is refused to a visitor who is not signed in. The SDK throws `REQUIRE_LOGIN` before the request leaves the browser, and the backend refuses the same call with `INVALID_REQUEST`, so a direct API call is refused as well. A project that has never set that option counts as **on**. If a signed out page genuinely needs the listing, turn Require Login off in the project settings. Table **names** are never filtered: the response carries every table in the project, whatever access group the records inside it live in. The per access group record counters are filtered to the caller: | Counter | Who receives it | | --- | --- | | `number_of_records_in_access_group_public` | Everyone, signed in or not. | | `number_of_records_in_access_group_authorized`, and every numbered group up to the caller's own | A signed in user, up to and including their own access group. | | `number_of_records_in_access_group_private`, `number_of_records_in_access_group_admin` | Admins and the project owner. | `number_of_records` and `size` are **not** filtered. Both are totals over every access group in the table, so `number_of_records` is normally larger than the counters you can see add up to. ### Querying tables To retrieve information for a specific table, pass an existing table name: ```js skapi.getTables({ table: 'my_collection', }).then(response => { console.log(response.list); // [{ // table: 'my_collection'; // number_of_records: string; // size: number; // number_of_records_in_access_group_public?: number; // number_of_records_in_access_group_private?: number; // number_of_records_in_access_group_authorized?: number; // number_of_records_in_access_group_admin?: number; // number_of_records_in_access_group_xx?: number; // for other access groups // }] }) ``` No `condition` is given here, and an omitted `condition` is an **exact** match on the table name. This returns the table named `my_collection` and nothing else. You can also query table names using `condition`. ```js skapi.getTables({ table: 'C', condition: '>' }).then(response => { console.log(response); // Table names starting from 'C' }) ``` In this example, `condition` is set to `>` and `table` is set to `C`. This returns table names that come after `C` in lexicographic order, such as `Cc`, `D`, `E`, and `F`. To fetch table names that start with a prefix, set `condition` to `>=`: ```js skapi.getTables({ table: 'my_', condition: '>=' }).then(response => { console.log(response); // Table names starting from 'my_' (for example, 'my_collection') }) ``` While you are exploring and do not know the exact spelling, pass `>=` rather than omitting `condition`. It is a prefix search, so it also surfaces related entries: in real data a table name very often carries a leading name shared with the rest of its data set, such as a source or dataset prefix, so `my_collection` and `my_collection_archive` are only found together by the prefix. An exact match finds one spelling and silently misses its siblings. When you already know the exact name, omitting `condition` is the exact match you want. To fetch table names that **end with** a value, set `condition` to `<=`: ```js skapi.getTables({ table: '_archive', condition: '<=' }).then(response => { console.log(response); // Table names ending with '_archive' (for example, 'my_collection_archive') }) ``` An 'ends with' search reads each table name from its last character backwards, and the results come back in that order. `fetchOptions.ascending` still applies, but it orders by that reversed reading rather than by the table name itself, so sort the returned list yourself if you need it ordered by name. So there are six ways the call can land: - no argument, or an empty query object: every table in the project. - `table` alone: an exact match on that name. - `table` with `condition: '>='`: every table name starting with that value. - `table` with `condition: '<='`: every table name ending with that value. - `table` as an empty string: rejected with `"table" should not be empty.` - `condition` with no `table`: rejected with `"table" is required for condition.` ```js skapi.getTables({ table: '' }); // Error: "table" should not be empty. skapi.getTables({ condition: '>=' }); // Error: "table" is required for condition. ``` Condition-based table search is useful when you need to check whether a table already exists before uploading data. For more detailed information on all the parameters and options available with the [`getTables()`](#doc-api-reference-database-gettables) method, please refer to the API Reference below: ### [`getTables(query, fetchOptions?): Promise>`](#doc-api-reference-database-gettables) # Access Restrictions Skapi database allows you to set access restrictions on records. This allows you to control who can access your records. You can add additional settings to your `table` parameter by using an `object` instead of a `string` in your `config.table`. This allows you to set access restrictions on records using the `access_group` parameter. The following values can be set for `table.access_group`: - Number 0 to 99: Integer from 0 to 99 can be set to define the access level. - `private`: Only the uploader of the record will have access. - `*`: Shorthand for `private`. The SDK converts it to `private` before the request is sent. - `public`: The record will be accessible to everyone. (Equivalent to number 0) - `authorized`: The record will only be accessible to users who are logged into your project. (Equivalent to number 1) - `admin`: The record will only be accessible to admins (access groups `90` ~ `99`) and the project owner. (Equivalent to number 99) If `access_group` is not set, what happens depends on **which form** the table was written in, because a table written as a plain string is not the same request as a table object with the `access_group` key left out. See [The `table` shorthand and `access_group`](#doc-database-access-restrictions-the-table-shorthand-and-access-group) below. ::: tip Users can only access records that have an access group that is the same or a lower number than the access group defined in their user profile. Admins (access groups `90` ~ `99`) and the project owner are the exception: they query and upload records in **every** access group, including `admin` (`99`). Fetching a single record by its `record_id` is stricter for admins in access groups `90` ~ `98`: a record in a higher access group than their own is refused with `No access to the record.` Admins in access group `99` and the project owner reach any record. Private records are off limits to all of them. See [Admin Permissions](#doc-admin-permissions-records). The user profile's access group is set by the project owner, and by admins with [`grantAccess()`](#doc-api-reference-admin-grantaccess), up to their own access group and only on accounts below their own. See [Granting an access group](#doc-admin-permissions-granting-an-access-group). ::: ::: tip Unless the user is referencing a private access granted record, the user cannot upload a record with `access_group` set to a higher level than their own access level. Admins and the project owner can. You can read more about [referencing records](#doc-database-referencing). ::: ::: warning Anonymous (unsigned) users can only create records with `access_group` set to `public`. ::: ## The `table` shorthand and `access_group` Everywhere a `table` is accepted, it can be written two ways, and the two do **not** mean the same thing when no `access_group` is given. Writing the table as a plain **string** is shorthand that pins access group `0` (`public`): ```js // These two calls are identical. The string form fills in access_group: 0 for you. await skapi.getRecords({ table: 'notes' }); await skapi.getRecords({ table: { name: 'notes', access_group: 0 } }); ``` That is true on `getRecords()`, on `deleteRecords()`, and on a `postRecord()` that **creates** a record (one called without a `record_id`). It is worth being deliberate about on a delete: `deleteRecords({ table: 'notes' })` does not empty the table, it deletes your public records in it, and the records the same table holds at any other access group are left exactly where they are. Writing the table as an **object** sends only the keys you actually wrote. Leaving `access_group` out of the object sends no access group at all, and the backend decides the scope of the call: - For a signed in user who is not the project owner, no access group resolves to group `0`, so it reads and deletes the same public records the shorthand would have. - For the **master** (project owner) account, it is not restricted to one group: the call spans every access group in the table. That is the reason the two forms are kept apart. A dashboard or an admin tool that wants to see a whole table wants the object form, and a call that must stay inside the public records wants the shorthand. ```js await skapi.getRecords({ table: 'notes' }); // public records only, for everyone await skapi.getRecords({ table: { name: 'notes' } }); // no group sent: every group, when the caller is the master ``` A listing that spans every group includes the `private` records of your users, and those come back with their `data` withheld. That is true of every way of listing them, so an admin tool reads the whole table without reading anyone's private payload. See [Private Records](#doc-database-access-restrictions-private-records). ::: warning On an **update**, neither form sends an access group. `postRecord(data, { record_id, table: 'notes' })` and `postRecord(data, { record_id, table: { name: 'notes' } })` both leave the record in whatever access group it is already in, and the backend fills the group back in from the stored record. This is what makes an update safe to write without repeating the group every time. To actually **move** a record between groups, name the group you want: `table: { name: 'notes', access_group: 'private' }`. Be aware that moving a record in or out of `'private'` is not a metadata change, see [Encrypting Private Record Data](#doc-database-encryption). ::: ## Creating Record With Access Restrictions Here's an example that demonstrates uploading record with `authorized` level access: ```js let data = { myData: "Only for authorized users" }; let config = { table: { name: 'ForAuthorizedUsers', access_group: 'authorized' } }; skapi.postRecord(data, config).then(record => { console.log(record); // Only the logged users will have access this record. }); ``` ## Fetching Records with Access Restrictions In order to fetch records with `access_group` that is not `public`, you need to specify the `access_group` you are trying to fetch from. In this example, we are trying to fetch records from the "ForAuthorizedUsers" table with `authorized` access. ```js let config = { table: { name: 'ForAuthorizedUsers', access_group: 'authorized' } }; skapi.getRecords(config) .then(response => { // response /** * endOfList: true, * list: [ * { * data: { myData: "Only for authorized users" }, * table: { name: 'ForAuthorizedUsers', access_group: 'authorized' }, * ... * }, ... * ], * startKey: 'end', * ... */ }); ``` ## Private Records Private records are only accessible to the uploader of the record. A private record that references another record is also readable by the users with private access to that record: its uploader, and the users it is shared with. This does not depend on the referenced record's access group, so a public record opens none of the private records attached to it. The project owner and admins read a private record's data only on the same terms as any other user. See [Private records](#doc-admin-permissions-private-records). The example below demonstrates uploading a private record: ```js let data = { myData: "My private data" }; let config = { table: { name: 'PrivateCollection', access_group: 'private' } }; skapi.postRecord(data, config).then(record => { console.log(record); // Only the uploader will be able to access this record. }); ``` Then, if someone else tries to fetch the record, they will get an error: ```js let config = { record_id: 'record_id_of_the_private_record' }; skapi.getRecords(config) .catch(err=>alert(err.message)); // User has no private access. ``` ## Grant Private Access Users can grant private access of their record to other users by using the [`grantPrivateRecordAccess(params)`](#doc-api-reference-database-grantprivateaccess) method. ```js skapi.grantPrivateRecordAccess({ record_id: 'record_id_of_the_private_record', user_id: 'user_id_to_grant_access' }) ``` When the user is granted access to the record, they will be able to fetch the record either if it's private or even if it has higher access group than the user. Access granted users can also see all the records that is referencing this record at all access groups including private records. You can read more about [referencing records](#doc-database-referencing). ## Remove Private Access Users can remove access of their private record from other users by using the [`removePrivateRecordAccess(params)`](#doc-api-reference-database-removeprivateaccess) method. Admins (access groups `90` ~ `99`) can remove private access from any record in the project, not only their own. On an [encrypted](#doc-database-encryption) record this stops the user from fetching it, but only the record's uploader can re-encrypt it, so a copy the user already holds stays readable to them. ```js skapi.removePrivateRecordAccess({ record_id: 'record_id_of_the_private_record', user_id: 'user_id_to_remove_access' }) ``` ## Changing the Access Group Clears Private Access Moving a record **into or out of** the `private` access group removes **every private access grant on it**. | Change | Grants | | --- | --- | | `private` to any other group | **cleared** | | any other group to `private` | **cleared** | | between two non-private groups | untouched | | no access group change | untouched | `private` is the only access group where a grant means *"this named user may read this one record"*. In every other group a grant only widens what an already-qualifying user may do, such as reading a record above their own access level or seeing the records referencing it, so those grants stay meaningful and are left alone. Leaving them in place on the way **out** of `private` would keep an access model the record no longer uses. Leaving them in place on the way **back in** would silently re-grant users the owner never re-approved. ```js // shared with a colleague await skapi.grantPrivateRecordAccess({ record_id, user_id: 'colleague_user_id' }); // this clears that grant, and so would moving it back to 'private' afterwards await skapi.postRecord(undefined, { record_id, table: { name: 'my_collection', access_group: 'authorized' } }); ``` :::warning The grants are gone, not suspended. If those users should still have access after the change, grant them again. ::: This is handled server side, so it applies to every project. ## Only the Owner Can Cross the Private Boundary A record can only be moved **into or out of** `private` by **the user who owns it**. Nobody else can change anything on a user's private record either, subscription settings included, or attach and delete its files. This holds for the project owner and admin accounts too. The two refusals below are what the project owner and admin accounts get, because they are the only other accounts allowed to update another user's record at all (on a read-only record, admins in access groups `90` ~ `98` get `Record is read only.` first). Any other user is refused before either check, for a private record or not, with: ```ts { code: "INVALID_REQUEST"; message: "User has no access to update this record."; } ``` A request from the project owner or an admin account that sets `table.access_group` of a user's private record to any other group, moving it out of `private`, is refused with: ```ts { code: "INVALID_REQUEST"; message: "User has no access to change the private access of the record."; } ``` From the project owner or an admin account, any other change to that record, including a request that keeps it in `private` or changes only its subscription settings, and moving another user's record into `private`, are refused with: ```ts { code: "INVALID_REQUEST"; message: "Only the owner of a record can move it into or out of the private access group."; } ``` The reason is that `private` is the only access group whose contents may be [end-to-end encrypted](#doc-database-encryption). Nobody but the owner holds the key, so a different account moving the record across that line would either seal it under a key the owner does not have, or publish bytes that nobody can decrypt. Both destroy the record while reporting success, and neither is recoverable. The rule is enforced whether or not encryption is enabled, so that a project cannot enable it later and discover its records were already stranded. On another user's non-private record, the project owner and admins in access group `99` can change the data and the other settings, including moving it between any two non-private access groups and changing its subscription settings. The project owner cannot make it read-only. Admins in access groups `90` ~ `98` can change none of its data or settings except its subscription settings. Files are a separate right: the project owner and every admin (access groups `90` ~ `99`) can attach files to it and delete its files, see [Files on Records of Other Users](#doc-database-handling-files-files-on-records-of-other-users). On a record posted by an anonymous user, subscription settings can only be kept or turned off. See [Admin Permissions](#doc-admin-permissions-updating-another-user-s-record) and [Subscription](#doc-database-subscription-who-can-change-subscription-settings). ## Allowing Others to Grant Private Access to Others By default, The owner of the record has access to grant private access of the uploaded record to others. The owner of the record can also allow other granted users to grant private access of the uploaded record to others. When uploading a record, if the uploader set `source.allow_granted_to_grant_others` to `true` users with private access to the record can grant access to other users as well. ```js skapi.postRecord(null, { table: { name: 'record_can_be_granted', access_group: 'private' }, source: { allow_granted_to_grant_others: true } }).then(r=>{ // now other users with an private access can also grant private access to the record (r) to others. }) ``` ## Listing Private Access Grants You can list records or users that have been granted private access using the [`listPrivateRecordAccess(params, fetchOptions)`](#doc-api-reference-database-listprivaterecordaccess) method. :::warning IMPORTANT Provide either `record_id` or `user_id` (at least one is required). ::: ```js skapi.listPrivateRecordAccess({ // Optional: one or both of these fields record_id: 'record_can_be_granted', user_id: 'user_id_to_check_granted' }).then(res => { // Response shape: // { // list: [ // { user_id: 'xxxx-xxxx...', record_id: 'record_id_123' }, // ... // ], // ... // } }) ``` # Encrypting Private Record Data Skapi can encrypt the `data` of your private records **in the browser**, before it reaches the database. The keys are derived from the user's own password and never leave their device, so the service provider running the backend cannot read the contents of a record its owner keeps to themselves. This is off by default, and the guarantee is narrower than "your data is encrypted". Read this whole page before turning it on. In particular: - Only the `data` attribute and the contents of attached files are covered. Index values, tags and filenames are not, and for many applications those are the sensitive part. - An encrypted file's `url` stops being directly fetchable, so `` and plain download links break for those files. - The strength is capped by the user's password, because Web Crypto offers no memory-hard KDF. - **Sharing** a record involves a public key that the provider serves, which is a weaker footing than the rest of the design and needs to be described accurately to a customer. - A forgotten password with no recovery code and no unlocked device means the data is gone. ## What is protected, and what is not Only the **value of the `data` attribute** is encrypted, and only on records whose `access_group` is `'private'`. Everything the database queries on stays in plaintext, because that is the only way your queries keep working: | Plaintext (the provider sees this) | Encrypted | | --- | --- | | `record_id`, `unique_id` | `data` | | `table.name`, `access_group` | the **contents** of files in `bin` | | `index.name` and `index.value` | | | `tags` | | | `reference` and the whole record graph | | | file **names**, sizes and upload times | | | `uploaded` / `updated` timestamps, record sizes | | | the list of users a record is shared with | | Only the `data` attribute and the **bytes** of attached files are covered. A file's name is part of its storage key, so it stays visible. ::: danger HTTPS required! Record encryption only runs on a page served over **https**. `localhost` and `127.0.0.1` also count, so local development works. The reason is the browser, not skapi. `crypto.subtle` is only exposed in a *secure context*. On plain http the page still gets `crypto.getRandomValues`, but `crypto.subtle` is `undefined`, so no key can be derived and nothing can be encrypted or decrypted. ::: ## The security claim, stated exactly The claim is not one sentence, it is two, because a record a user keeps to themselves and a record they share with someone else rest on different foundations. **For a user's own private records, never shared:** > A service provider who dumps the database, the storage bucket, and every request log > cannot recover the record's `data` without a successful offline guess against the user's > password. No key comes from the server on this path. The master key is derived in the browser from the password, so this holds on cryptography alone. **For records the user has shared with someone else:** > The provider cannot recover the record's `data` by reading its own database. It *can* > obtain that record's data key by serving a forged public key at the moment the user > shares, which the user can detect by comparing key fingerprints, and which > `trustPolicy: 'strict'` prevents outright. Sharing requires fetching the other person's public key, and the provider serves that directory. See [Key substitution](#doc-database-encryption-key-substitution-the-residual-risk-in-sharing) for the full picture, because this is the first thing a security auditor will test. ### The ceiling on both Both are bounded by **password entropy**, because the Web Crypto API offers only PBKDF2 (no Argon2id, no memory-hard KDF). Skapi's default minimum password is six characters, and a six-character password falls to an offline attack in minutes. If you are making this promise to a customer, set `minPasswordLength` and enforce a real password policy in your signup form. A user who keeps their [recovery code](#doc-database-encryption-recovery-codes) is better off, since that is 128 random bits rather than a memorable string, but the password remains the floor for anyone who does not. ## Turning it on ```js const skapi = new Skapi("", { encryption: true }); ``` `encryption` is an option of the Skapi class, and it only takes effect when the class is initialized. There is no method that turns it on later: an instance built without this option saves the `data` of every record as plain text for its entire lifetime, and enabling it afterwards does not go back and encrypt what was already saved. It is listed with the rest of the initialization options in [Advanced Settings](#doc-introduction-codebase-advanced-settings). With options: ```js const options = { encryption: { iterations: 600000, // PBKDF2 cost. Default 600000, minimum 100000. minPasswordLength: 12, // refuse to enroll a weaker password. Default 0 (off). persistDevice: true, // stay unlocked across a page reload. Default true. recovery: 'code', // issue a one-time recovery code. Default 'code'. trustPolicy: 'tofu', // 'tofu' (default) or 'strict'. See Sharing. withheld: 'null' // 'null' (default) or 'sentinel'. See below. } }; const skapi = new Skapi("", options); ``` Then write records exactly as you always have: ```js await skapi.postRecord( { diagnosis: 'confidential' }, { table: { name: 'notes', access_group: 'private' } } ); const res = await skapi.getRecords({ table: { name: 'notes', access_group: 'private' } }); console.log(res.list[0].data); // { diagnosis: 'confidential' } ``` There is no key to manage and nothing for the end user to do. Logging in unlocks encryption; a page reload stays unlocked. ## Changing the access group If you change a record's access group to anything other than `'private'`, the data is written back **decrypted**, as an ordinary object. A record that is no longer private is no longer unreadable: ```js // starts encrypted const rec = await skapi.postRecord( { note: 'secret' }, { table: { name: 'notes', access_group: 'private' } } ); // now stored in the clear, readable by anyone await skapi.postRecord( { note: 'secret' }, { record_id: rec.record_id, table: { name: 'notes', access_group: 0 } } ); ``` The reverse also holds: moving a public record to `'private'` encrypts it on the way in. ::: warning A group change alone publishes the plaintext You do not have to pass the data along with the group change, and that is worth knowing before you write the call. Moving an encrypted record to a non-private group **without** restating its data does not leave the ciphertext stranded: the SDK decrypts what is stored and writes it back in the clear, because a record nothing will ever try to decrypt is worse than one that is readable on purpose. The consequence is that a bare access-group change is a publish. If the intent was only to reorganize a table, move the record to another private group instead. The SDK can only do this while encryption is unlocked and the caller can actually read the record. A session that cannot decrypt it is refused rather than allowed to strand or destroy the payload. ::: ### Attachments move with the record Files are converted in whichever direction the record is going: sealed files come back to plaintext when a record leaves `'private'`, and plaintext files are sealed when it arrives. Without this, declassifying produced a public record holding files nobody could ever open again, because the payload was decrypted while the key went with the envelope. The order is what makes each direction safe to interrupt: | Direction | Order | If it dies halfway | | --- | --- | --- | | `private` to anything | files first, then the group flip | still private, some files already plaintext. Readable, and re-running finishes it | | anything to `private` | group flip first, then the files | private with its data sealed, some files still in the clear. Less protected than intended, nothing lost | Neither is atomic and neither can be: a group change is one write, and every file is a separate object. What they are is **monotonic**. No interruption destroys content, and re-running the same update completes the job. ::: warning This costs requests A group change on a record with attachments downloads, re-encodes and re-uploads every one of them. An update that states a non-private group also costs one extra read, to find out whether there are any sealed files at all. Changing the access group of a record with many large files is not a cheap operation. ::: ### The service owner cannot change these settings for someone else A master account can update any non-private record in its project, but **not** move someone else's record into or out of `'private'`. That is refused in both directions, and the SDK refuses it earlier with `ENCRYPTION_NOT_RECORD_OWNER` so the reason is clear before a round trip: - Making **someone else's record private** would seal it under the master's key, with the envelope naming the master as owner while the record belongs to someone else. The binding check then refuses it for everyone, the real owner included. The record would be destroyed and the call would report success. - **Declassifying someone else's** encrypted record cannot work either, since the master has no key to decrypt what it would have to write back in the clear. Encryption operates only on records you own, whatever access level you hold. A master who needs one of these changes has to have the owner make it. This is enforced in the **backend**, not only in the SDK, so a direct REST call is refused too. Declassifying someone else's private record, by setting its `table.access_group` to any non-private group, is refused with: > User has no access to change the private access of the record. Making someone else's record private, and any other change to someone else's private record, including a request that keeps it in `'private'` or changes only its subscription settings, are refused with: > Only the owner of a record can move it into or out of the private access group. A master may still move someone else's record freely between any two **non-private** groups, but cannot change anything on someone else's private record, nor attach or delete its files. The rule is specifically about the private boundary, because `'private'` is the only group whose contents may be encrypted, and no amount of privilege substitutes for a key that only the owner has. See [Only the Owner Can Cross the Private Boundary](#doc-database-access-restrictions-only-the-owner-can-cross-the-private-boundary). On its own records a master follows the usual rules, with one exception: the project owner's account is not a user of the project, so it cannot make its own records private or read-only, or give them subscription settings. See [Admin Features](#doc-admin-intro-what-project-owners-cannot-do). ## Private grants are cleared at the boundary Crossing into or out of `'private'` **removes every private-access grant on the record**. `'private'` is the only access group where a grant means *"this named user may read this one record"*. In every other group a grant only widens what an already-qualifying user may do, such as referencing the record, so those grants stay meaningful and are left alone. | Change | Grants | | --- | --- | | `private` to anything | **cleared** | | anything to `private` | **cleared** | | between two non-private groups | untouched | | no group change | untouched | Leaving them in place on the way *out* would keep an access model the record no longer uses. Leaving them in place on the way *back in* would silently re-grant users the owner never re-approved, and with encryption enabled it would produce a record whose ACL says "shared" while its key wraps say otherwise: the ACL would let those users fetch it and the crypto would refuse them. This runs in the record stream, so it applies **whether or not encryption is enabled**. If the users should still have access after the change, grant them again. ::: tip State the table on updates When you update a record without a `table`, the SDK has to fetch the record to learn its current access group, which costs one extra request. Passing `table: { name, access_group }` avoids it. ::: ## Sharing a record The record's owner can give other users decrypt access. This works through the normal grant API, with the key wrapping handled for you: ```js await skapi.grantPrivateRecordAccess({ record_id: rec.record_id, user_id: 'the-other-users-id' }); ``` Behind that call the SDK fetches the other user's public key, wraps this record's data key to it, and writes the result onto the record **before** granting access at the ACL level, so a failure never leaves a grant that the recipient cannot use. The grantee then reads the record normally, with their own session. **The owner does not need to be online for that**: the wrapped key sits on the record permanently. The owner is only needed at the moment of granting, because only someone who can already decrypt the record can wrap its key for someone new. Revoking removes the wrap **and rolls the data key**, re-encrypting the record so the revoked user cannot read future versions: ```js await skapi.removePrivateRecordAccess({ record_id: rec.record_id, user_id: 'the-other-users-id' }); ``` Revocation is **forward-only**. It cannot un-read what they already read, and if they kept a copy of the old ciphertext and their old wrap, that copy stays readable to them forever. ::: warning A group change clears grants Moving a record into or out of `'private'` removes every grant on it. See [Private grants are cleared at the boundary](#doc-database-encryption-private-grants-are-cleared-at-the-boundary). ::: ### Rules for sharing - Only the **owner** can share or revoke an encrypted record, because both mean writing to it. Delegated granting via `source.allow_granted_to_grant_others` does not work on encrypted records. An admin can still remove a user's private access to it, which stops that user from fetching the record, but only the owner can roll the data key; an admin whose session has encryption enabled gets `ENCRYPTION_NOT_RECORD_OWNER` after the access is removed. - The recipient must have logged in at least once with encryption enabled, so that they have a published key. Granting to a user with no key throws `ENCRYPTION_RECIPIENT_HAS_NO_KEY` and changes nothing. - Each recipient adds roughly 230 bytes to the record, carried on every read and write of the envelope. On a large record the payload itself is stored separately and is **not** re-uploaded when you share it: see [Large payloads](#doc-database-encryption-large-payloads). ### Key substitution: the residual risk in sharing This is the one place where the guarantee rests on trust rather than on mathematics, so it is worth understanding properly rather than being reassured about. #### The attack Alice wants to share a record with Bob. Her browser asks the backend for Bob's public key. The backend returns a key **whose private half the provider holds**. Alice's SDK wraps the record's data key to it, and the provider can now open that record. It can be made invisible to both of them: having obtained the data key, the provider can also wrap it for Bob's real key, so Bob reads the record normally and nothing looks wrong. And because a record's data key is stable across updates, one successful substitution yields that record's contents from then on, not only the version that existed at that moment, until a revoke rolls the key. #### What it does not reach Three limits, and they are the reason this does not sink the design: - **It is an active attack, not a passive one.** A provider who dumps the database, the bucket and every request log still gets nothing. This requires deliberately serving a forged key at the moment of a specific share. That is a different category of act: it lives in deploy history and source control, where it can be audited. - **It cannot touch a user's own unshared records.** That path never asks the server for a key. The exposure is limited to records the user chose to share, and only to shares made after the attack begins. - **It compromises no identity.** What the provider gets is one record's data key. Not the user's master key, not anyone's private key, not any other record. #### Why no protocol fixes it Every end-to-end system with a provider-hosted key directory has exactly this property: Signal, WhatsApp, iMessage, Proton. It is a property of the trust topology, not a flaw in this implementation. A signature scheme is the tempting wrong answer. Bob signing his own public key with his own identity key is self-referential, so a provider substituting both produces a signature that verifies perfectly. Closing this needs a trust root the provider does not control. #### The three mitigations, in increasing order of cost **1. Fingerprint pinning.** The SDK refuses to accept a *changed* key silently. If a peer's fingerprint differs from the one first seen, the grant throws `ENCRYPTION_PEER_KEY_CHANGED`, because that is what a legitimate account reset looks like and also what an attack looks like, and guessing between them is not the SDK's call: ```js // after verifying the fingerprint with them out of band await skapi.pinPeerKey({ user_id: 'their-id', fingerprint: 'the-verified-value' }); ``` Pins are stored encrypted under the user's own master key, so the provider can destroy them (which is loud: every peer becomes unseen again) but cannot edit them undetectably. This is Signal's safety numbers. It means a provider cannot silently swap a key it has already been observed serving. **2. `trustPolicy: 'strict'`.** Requires a pin before *any* first share, so there is no trust-on-first-use window at all. This genuinely closes the hole. The cost is that users must verify a fingerprint before they can share with someone new, which is right for a security-conscious tenant and too much friction for a consumer app. **3. Key transparency (not implemented).** Publish every key the directory serves into an append-only log with inclusion proofs, so a client can verify that the key it was handed is the same one everyone else was handed, and that a peer's key history contains no unexplained entries. This is what Apple's Contact Key Verification and WhatsApp's Key Transparency do. It is the only mitigation that closes the hole without asking users to do anything, and it is a substantial project: a verifiable log service, proof generation, and client-side auditing. #### What to tell a customer Scope it honestly. An auditor will accept this: > For your own private records, we cannot read them: the key never leaves your device. For > records you share, we cannot read them by reading our database. The residual risk is that > we serve you a forged public key at the moment you share, which you can detect by > comparing fingerprints, and which strict mode prevents outright. An auditor will not accept a flat "we cannot see your data" over a trust-on-first-use directory, because verifying that claim is the first test they will run. ## Attached files Files attached to a private record are encrypted too, under a key derived from that record's data key. Anyone who can read the record can open its files, with no extra key distribution, and a grantee gets both at once. Only the record's own user can attach files to a private record or delete its files. The project owner and admins, who may do both on another user's non-private record, are refused here. See [Files on Records of Other Users](#doc-database-handling-files-files-on-records-of-other-users). Nothing changes in how you upload: ```js await skapi.postRecord( { title: 'contract' }, { table: { name: 'notes', access_group: 'private' } }, [{ name: 'doc', file: myFile }] ); ``` Reading requires `getFile()`, which decrypts: ```js const rec = (await skapi.getRecords({ record_id })).list[0]; const f = rec.bin.doc[0]; f.encrypted; // true f.filename; // 'contract.pdf' (names are NOT encrypted) f.size; // the PLAINTEXT byte length f.stored_size; // the larger, real size on storage const blob = await f.getFile('blob'); // decrypted await f.getFile('download'); // decrypted, then saved ``` ::: danger The url is ciphertext `record.bin[].url` serves the encrypted bytes. These stop working for an encrypted file and there is no SDK-side fix, because the url escapes into places the SDK cannot see: - ``, `