Verified events
Events sent with a server key, or by your own Apple or Android app proven by the device, are marked verified, so you can tell them apart from events anyone holding the public key could have sent.
An ingest key ships inside your app or your web page, so anyone can copy it and send events that look like your app's. Lyrelog marks the events it can tell apart from those as verified, in three ways:
- events sent with a server key, a secret that only your servers hold,
- events sent by your own Apple app on a real device, which Apple proves with App Attest, and
- events sent by your own Android app on a real device, which the device's secure hardware proves with Key Attestation.
What verified means
A verified event can't have been sent by someone who copied the public key out of an app or a web page. With a server key, it came with a key that only the project's servers hold. With App Attest, it came from the project's genuine app, signed by its team, on a genuine Apple device. With Key Attestation, it came from the project's genuine Android app, signed with the project's certificate, on a real Android device with its original, locked system.
It doesn't prove that what the event says is true. A server can send a wrong value, and someone using the real app on a jailbroken device could still make it send events. A verified event is only as trustworthy as the code that sent it.
Events sent with the public ingest key and no proof of the app are not verified: anyone holding that key could have sent events just like them. That is most events from web pages and from apps that don't use App Attest or Key Attestation, and it is expected.
Who verifies
| Sender | Key | Its events | verified_by |
|---|---|---|---|
| Your server | Send events from a server, lyr_srv_ | Verified | server |
| Your Apple app on a real iPhone, iPad or Apple Watch, set up for App Attest | Send events, lyr_ing_ | Verified | app_attest |
| Your Android app on a real device, set up for Key Attestation | Send events, lyr_ing_ | Verified | key_attestation |
| Anything else with the ingest key | Send events, lyr_ing_ | Not verified | empty |
| Anything with a full-access key | Full access, lyr_adm_ | Not verified | empty |
Lyrelog sets this on every event at ingest, from the key the batch came with and, for an ingest
key, the App Attest or Key Attestation token it carries. A client can't set it: a line that sends verified_by
itself is rejected with unknown fields: verified_by.
A server key can only append events, like an ingest key; it can't read them. See Keys for how to make one.
In the dashboard
- In the events list, a small shield next to the event name marks a verified event.
- An opened event shows a Verified badge in its header. Under Context, Sender says Verified, server key, Verified, App Attest, Verified, Key Attestation or Not verified, public key.
- In the explorer, the Filter menu has a field Verified by
with the values Server key, App Attest, Key Attestation and Not verified (in
the URL:
server,app_attest,key_attestationandnone). Pick all but Not verified to see only verified events, or Not verified for the rest.
The read API returns verified_by on each event ("server", "app_attest",
"key_attestation", or "" when not verified) and filters by it with verified=server,
verified=app_attest, verified=key_attestation or verified=none, or several at once
(verified=server|app_attest|key_attestation).
Servers
A backend (Node, Python, Go, Java or Kotlin on the JVM, or curl from a server)
should send with a server key, lyr_srv_...:
its events are verified, and it has no daily limit per address.
Give the SDK the server key where the examples show lyr_ing_...; nothing else changes.
Keep it like any secret: in your server's environment or secret store, never in an app, a web page or a repository. If it leaks, revoke it and make another.
Apple apps (App Attest)
Apple's App Attest lets an app prove to a server that it is the genuine app, signed by its team,
running on a genuine Apple device. The Swift SDK
does it for you, and so do the React Native and
Flutter SDKs on iOS, through the Swift SDK. Lyrelog stores
the events of a proven app as verified (verified_by is app_attest).
Set it up
- Find your app's App ID: your Team ID, a dot and the bundle id, like
ABCDE12345.com.example.app. The Team ID is in your Apple Developer account, under Membership. - In Lyrelog, open Project settings. The section Verified events from your Apple apps is there when the project has the iOS app platform. Add the App ID with Add. An owner can add up to 10, one per app (an iPhone app and its watch app have different bundle ids).
- In Xcode, add the App Attest capability to the app target (Signing & Capabilities). That
is the entitlement
com.apple.developer.devicecheck.appattest-environment. Set it toproductionfor App Store and TestFlight builds. Without it Apple uses its development environment, which also verifies. - Use the Swift SDK. Its option
appAttestistrueby default, so there is nothing else to code. The same goes for React Native and Flutter (their option isattest): the project's settings are the same, since the Swift SDK underneath does the work.
To turn it off, remove the App IDs (events arrive unverified, as before), or set
appAttest: false in the app.
How it works
- Once per install, the SDK makes a key in the device's Secure Enclave and Apple attests it over a one-time challenge from Lyrelog. Lyrelog checks Apple's certificate chain and that the app is one of the project's App IDs, and keeps the key's public half: one per install, deleted after 180 days unused.
- The SDK then gets a token, valid for a day, and sends it with each batch. It renews the token with a signature from that key (an assertion), whose counter can't be replayed.
- Sending never waits for this. Until the app has a token, and whenever anything fails, events are sent and stored unverified. A batch is never refused because of App Attest.
Where it doesn't apply
App Attest works on real iPhones, iPads and Apple Watches. These send unverified events, even with everything set up:
- Macs (Apple doesn't offer App Attest there),
- the simulator,
- most app extensions,
- devices that don't support App Attest.
The routes and the header are in the HTTP API.
Accept only verified events from the iOS app
Off by default. In the same settings section, Accept only verified events from the iOS app
makes Lyrelog hold back every unverified batch whose events say platform: ios: it answers
425 Too Early, and the SDK keeps the batch and sends it again later. A new install's first events
wait a few seconds for its token and then arrive verified, so nothing is lost there.
Turn it on only when everyone has a version of the app with App Attest set up. Until then, events from older versions, from the simulator and from an iPad app running on a Mac can never prove themselves: they wait on the device, up to what the SDK keeps (20 MB and 7 days), and are never stored. Events from other platforms, and from a server key, are accepted as before.
Android apps (Key Attestation)
Android's Key Attestation lets an app make a key inside the phone's secure hardware (its trusted
execution environment, or a StrongBox chip) and get a certificate chain from the device, signed
up to Google, that describes the key, the app and the state of the phone. Lyrelog checks that
chain itself: no Google account, Play Integrity or Google Cloud project is needed. The
Android SDK does it for you, and so do the
React Native and Flutter
SDKs on Android, through the Android SDK. Lyrelog stores the events of a proven app as verified
(verified_by is key_attestation).
Set it up
- Find your app's package (its application id, like
com.example.app) and the SHA-256 fingerprint of the certificate it's signed with:- For builds installed from Google Play, Google signs the app: in Play Console, open the app, then Test and release, App integrity, and copy the SHA-256 of the App signing key certificate.
- For builds you sign yourself (an upload key, or the debug key in development), run
./gradlew signingReportand copy the SHA-256 of that variant.
- In Lyrelog, open Project settings. The section Verified events from your Android apps is there when the project has the Android app platform. Add the package and the fingerprint with Add; add the same package again with another fingerprint for each certificate that signs builds that send events (up to 5 per package, 10 packages).
- Use the Android SDK. Its option
attestistrueby default, so there is nothing else to code. The same goes for React Native and Flutter: the project's settings are the same, since the Android SDK underneath does the work. In a React Native or Flutter project,./gradlew signingReportruns in the app'sandroidfolder.
To turn it off, remove the packages (events arrive unverified, as before), or set
attest = false in the app.
What is checked
- The chain is signed, certificate by certificate, up to one of Google's attestation roots, and none of its certificates is on Google's list of revoked ones.
- The key lives in the phone's secure hardware, was made there, and answers a one-time challenge from Lyrelog.
- The phone booted its original, verified system and its bootloader is locked.
- The app is one of the project's packages, signed with one of its certificates.
Lyrelog then keeps the key's public half (one per install, deleted after 180 days unused) and gives the app a token, valid for a day, that it sends with each batch. It renews the token by signing a new one-time challenge with that key. Sending never waits for this: until the app has a token, and whenever anything fails, events are sent and stored unverified. A batch is never refused because of Key Attestation.
Where it doesn't apply
These send unverified events, even with everything set up:
- emulators (they have no secure hardware, and their chains don't lead to Google),
- rooted phones, phones with an unlocked bootloader or a custom system,
- phones without hardware-backed keys (rare since Android 8),
- builds signed with a certificate the project doesn't list.
The routes are in the HTTP API.
Accept only verified events from the Android app
Off by default, and it works like the iOS one:
with it on, every unverified batch whose events say platform: android gets 425 Too Early and
waits on the device. Turn it on only when everyone has a version with Key Attestation: events from
older versions, emulators and rooted or unlocked phones can never prove themselves and are never
stored.
Web pages, through your own server
A web page can't hold a server key: anything in the browser can be read. To get verified events from a page, relay them through your own backend. The page sends to a route on your site, and the route forwards the batch to Lyrelog with the server key.
Be clear about what that proves. These events are verified only in the sense that they passed through your server. Anyone can post to a route on your site, so the relay should accept events only from your own signed-in sessions, and cap what one session sends. A relay that takes anything from anyone verifies nothing.
In the page, point the JavaScript SDK's endpoint at the relay. It is
a base URL: the SDK posts to <endpoint>/v1/events:batch. apiKey can't be empty, but the relay
replaces it, so any placeholder works:
export const log = Lyrelog.init({
endpoint: "https://example.com/api/lyrelog", // posts to /api/lyrelog/v1/events:batch
apiKey: "relay", // replaced by the server key on your server
});The relay, as a Next.js route handler (app/api/lyrelog/[...path]/route.ts):
import { getSession } from "@/lib/auth"; // your own sign-in
export async function POST(request: Request) {
const session = await getSession(request);
if (!session) return new Response(null, { status: 401 });
const encoding = request.headers.get("Content-Encoding");
const upstream = await fetch("https://ingest.lyrelog.com/v1/events:batch", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LYRELOG_SERVER_KEY}`, // lyr_srv_..., server only
"Content-Type": request.headers.get("Content-Type") ?? "application/x-ndjson",
...(encoding ? { "Content-Encoding": encoding } : {}),
},
body: await request.arrayBuffer(),
});
const headers = new Headers({ "Content-Type": "application/json" });
const retryAfter = upstream.headers.get("Retry-After");
if (retryAfter) headers.set("Retry-After", retryAfter);
return new Response(await upstream.text(), { status: upstream.status, headers });
}Worth knowing:
- Pass the status and
Retry-Afterback unchanged: the SDK decides from them whether to retry or drop a batch. - A
401or403makes the SDK stop sending until the page reloads. Start the client once the visitor has signed in, not before. - The country comes from the address that sends the batch to Lyrelog, which is now your server's. Relayed events carry your server's country, not the visitor's.
- Add the relay's address to your Content Security Policy's
connect-srcif you set one ('self'covers a route on the same site).
Other apps and web pages
Events from Apple apps without App Attest, from Android apps without Key Attestation, and from web pages that send directly use the public ingest key with no proof of the app, so they are not verified. A web page can get verified events through your own server. Two limits keep a copied key from doing much harm:
- the plan's monthly events, for the whole organization, and
- the daily share of one address, below.
The daily share of one address
With a public key (an ingest key, or a full-access key), one sending address may send at most a fiftieth of the plan's monthly events in a UTC day, across the organization's projects. IPv6 addresses count per /64. Only events that aren't verified count.
| Plan | Events a day from one address |
|---|---|
| Free | 20,000 |
| Pro | 200,000 |
| Business | 4,000,000 |
| Unlimited | No limit |
That is far more than one device sends. It exists so that a key copied out of an app can't spend the organization's month from one machine. Verified events (from a server key, App Attest or Key Attestation) don't count toward it.
Past it, that address gets 429 with a Retry-After of at most an hour, until the next UTC
day. Other addresses keep sending. The SDKs retry it like any 429, keeping events within their
queue limits. The body is in the HTTP API.
If one of your servers reaches it, it should be using a server key.