Flares Cloud is not currently available to new customers. This documentation is kept for the projects already running on it, and stays accurate for them. What happened.

Flares Developer Docs

Building a mobile app

How an iOS, Android or cross-platform app talks to a project, and which key belongs in a binary anyone can open.

A Flares Cloud project gives a mobile application the three things it usually needs from a backend: somewhere to keep data that syncs, a way for people to sign in, and somewhere to run code you do not want on the device. There is no Flares mobile SDK — everything here is plain HTTPS and one websocket, which every mobile platform already speaks.

What runs where

your app  ──HTTPS──►  Basket DB      collections, records, queries
          ──HTTPS──►  Auth           sign-up, sign-in, sessions
          ──HTTPS──►  Functions      your backend PHP, at a URL
          ──WSS────►  realtime       changes pushed as they happen

All four are addressed under one project id and share one pair of keys. Projects explains the shape; what follows is only what changes when the client is a phone.

Which key goes in the app

The public key, and only ever the public key. An app binary is a file on a stranger's device: it can be unzipped, decompiled and read. Assume anything you ship is published.

KeyIn your app?Why
basket_public_…Yes It is designed to be public. It cannot change your schema, read past your rules, or administer users.
basket_secret_…Never It bypasses rules, edits schema and administers users. In a binary it is a full compromise of the project, and rotating it means shipping an app update to every user.
Obfuscation, string encryption and native storage do not make a secret key safe to embed. They raise the effort of extracting it from minutes to an afternoon. If a task needs the secret key, it belongs in a Function, which your app calls.

So what protects the data?

Not the key — the key only says which project you are talking to. Two things do the actual work, and a mobile app needs both:

  • Rules on each collection decide who may read and write which records. A rule can refer to the signed-in user, so “a person may only read their own orders” is enforced by the platform rather than by your client remembering to filter. Rules →
  • Auth establishes who the person is, and gives you a user token to send alongside the public key. Sessions on a device →

A public key with no user token is an anonymous caller. Design your rules from that starting point: write them as though every request came from somebody who downloaded your app to see what it does, because one of them will.

The three headers you will use

Authorization: Bearer basket_public_…      always
X-Basket-User-Token: eyJ…                  Basket, when signed in
X-Flares-User-Token: eyJ…                  Functions, when signed in

The user token is the same token in both cases; only the header name differs, because Basket and Functions are separate services that each read their own.

A first request

Nothing platform-specific — this is an ordinary GET with two headers.

// Swift
var request = URLRequest(url: URL(string:
    "https://cloud.flaresinc.com/v1/projects/prj_…/collections/orders/records")!)
request.setValue("Bearer basket_public_…", forHTTPHeaderField: "Authorization")
request.setValue(accessToken, forHTTPHeaderField: "X-Basket-User-Token")

let (data, response) = try await URLSession.shared.data(for: request)
// Kotlin
val request = Request.Builder()
    .url("https://cloud.flaresinc.com/v1/projects/prj_…/collections/orders/records")
    .header("Authorization", "Bearer basket_public_…")
    .header("X-Basket-User-Token", accessToken)
    .build()

client.newCall(request).execute().use { response -> /* … */ }

The request and response shapes are the same on every platform and are documented once, in the Basket API reference.

What Flares does not do for you

Being direct about this saves you discovering it three weeks in:

Not providedWhat to do instead
Offline persistence and sync Basket has no on-device cache or conflict resolution. Cache in your own store — Core Data, Room, SQLite — and treat Basket as the source of truth you reconcile against on reconnect.
Push notifications There is no push service. The realtime websocket delivers changes while your app is running; for notifications when it is not, use APNs or FCM from a Function.
A native SDK Use your platform's HTTP and websocket clients directly. The API is small enough that a thin wrapper of your own is usually better than a dependency.
File and image storage Storage is not available yet. Records hold JSON; large binaries need somewhere else for now.
Social sign-in Auth supports email and password, and email one-time codes. There is no Apple, Google or Facebook sign-in.

Platform network settings

Everything is HTTPS on the default port with a public certificate, so neither platform needs an exception:

  • iOS — no App Transport Security exception is required. Do not add NSAllowsArbitraryLoads for Flares; you do not need it, and it weakens every other connection your app makes.
  • Android — works under the default network security configuration. Cleartext is never needed.

If you pin certificates, pin to the certificate authority rather than a leaf certificate. Certificates are renewed on a schedule you do not control, and a pinned leaf turns a routine renewal into every installed copy of your app losing its backend at once.

Where to go next