Authentication
API keys, App ID, and identity verification.
Authenticate product APIs with secret project keys, and mobile SDK calls with a publishable App ID.
Bearer API keys (backend only)
Pass your project API key in the Authorization header. The key resolves exactly one project. Do not send a trusted project_id from the client — tenancy comes from the key.
Authorization: Bearer cr_sk_...
Idempotency-Key: acme_event_8392_user_123Key prefixes
cr_sk_... # secret project API key (backend only)
cr_app_... # publishable mobile App ID (safe to embed in apps)- Secret keys (
cr_sk_) may call all public product APIs for their project. There is a single secret prefix — no separate production vs sandbox/test key types. - Publishable App IDs (
cr_app_) may only call/mobile/*endpoints. - There are no per-secret-key capability scopes in v1.
- Create and revoke secret keys from the Dashboard API Keys page. The mobile App ID is created automatically per project and stays copyable under Push → Push settings → Platforms.
Mobile App ID
React Native apps initialize with ComRaid.initialize({ appId: COMRAID_APP_ID }) and send:
X-ComRaid-App-Id: cr_app_...This grants category sync and anonymous push registration only. It never authorizes Notification sends, contact lists, segments, Dashboard data, API keys, FCM credentials, or delivery inspection.
Never embed cr_sk_... in mobile apps. Use your product backend as a proxy for those APIs. See the React Native SDK for register and login(externalUserId, jwt).
Mobile login
After anonymous POST /mobile/subscriptions, the response includes a subscription_credential (issued once). Store it with the Subscription id. Then bind the device with ComRaid.login(externalUserId, jwt) (POST /mobile/subscriptions/{'{id}'}/login).
- Body always includes
external_user_idandsubscription_credentialonce issued. - Projects can require an RS256
jwtfor Identity verification (issuercomraid:{'{project_id}'}, audiencecomraid:identity, recommend 5 minutes, max 10). Configure public keys and the required toggle under Push settings. - Identity verification stays optional per project. Leave the required toggle off when you do not need verified login — optional mode allows login without a JWT (unverified bind). Any supplied invalid JWT is still rejected.
- When the same FCM/APNs token registers without ownership, the previous Endpoint is deactivated and unbound (last-writer-wins).
- Token rotation keeps the same
subscription_idviaPOST /mobile/subscriptions/{'{id}'}/tokenwithsubscription_credential. The SDK refreshes the device token this way; do not re-register anonymously for the same install when you still hold the credential.
New projects default to required verification. Existing projects stay optional until an admin enables the toggle. Enable only after uploading an active identity key — required mode fails closed without one.
Minting an Identity verification JWT
When verification is on, your backend mints a short-lived RS256 JWT and the app passes it to ComRaid.login(externalUserId, jwt). Use @comraid/node identity.createToken so claims match server verification.
# 1. Generate a key pair (keep the private key on your backend only)
openssl genrsa -out comraid-identity.pem 2048
openssl rsa -in comraid-identity.pem -pubout -out comraid-identity.pub.pemUpload comraid-identity.pub.pem under Push settings → Identity verification (choose a kid). Then mint and return a token from your session endpoint:
import { identity } from "@comraid/node";
import { readFileSync } from "node:fs";
const privateKey = readFileSync("./comraid-identity.pem", "utf8");
export function mintComRaidIdentityJwt(externalUserId) {
return identity.createToken(externalUserId, {
projectId: process.env.COMRAID_PROJECT_ID,
privateKey,
kid: process.env.COMRAID_IDENTITY_KID,
expiresIn: 300, // seconds; default 300, max 600
});
}
// App: ComRaid.login(externalUserId, mintComRaidIdentityJwt(externalUserId))See the Node SDK method reference for parameters. Leaving verification off skips this flow entirely.
Mobile credential APIs
With X-ComRaid-App-Id and subscription_credential, the Subscription can also call:
POST /mobile/subscriptions/{'{id}'}/session— session heartbeat (HTTP-only — no SDK method today)POST /mobile/subscriptions/{'{id}'}/opt-out— opt out of push on this SubscriptionPOST /mobile/subscriptions/{'{id}'}/opt-in— opt back inPUT /mobile/subscriptions/{'{id}'}/attributes— upsert Subscription-scoped Attributes
Prefer the platform SDK when it wraps login, logout, token rotation, opt-in/out, and attributes. Request and response schemas are in the API Reference (Mobile tag).
Mobile session (HTTP-only)
POST /mobile/subscriptions/{'{id}'}/session (mobileSubscriptionSession) records an SDK session: increments session_count, refreshes last_seen_at, and upserts first-class Properties (locale, timezone, app/OS versions). It is distinct from Contact Attributes.
There is no SDK method for session today — call it over HTTP with X-ComRaid-App-Id and subscription_credential. Do not invent wrappers in app code docs.
Session is HTTP-only until product work adds an SDK wrapper. Prefer the SDK for register, login, logout, token rotation, opt-in/out, and attributes when your platform ships those methods.
Idempotency
For retry-safe creates that trigger communication (especially POST /messages and POST /campaigns), send an Idempotency-Key header. Keys are scoped to the authenticated project.
- Same key + same body → stored response, no duplicate rows.
- Same key + different body →
409 idempotency_conflict. - Same key while the first request is in flight →
409 idempotency_in_progress.
Host
https://api.comraid.io