Arifa — Real-Time Notifications API

Arifa provides real-time WebSocket notifications for web and mobile apps. Developers can send messages instantly using a secure API and deliver them to an online or offline user.

Arifa is lightweight, fast, and made for production use.

Key Features

Real-time WebSocket delivery
Test API keys (valid 4 hours)
Offline message queue
Weekly cleanup of delivered payloads
UUID-based user identification
End-to-end secure connections

What You Need

Arifa account
Subscription plan for Live Keys
Test Key (4 hours only) for development

Getting Started

1. Create an Account

Visit:

https://app.arifa.dev

2. Subscription Required for Live Keys

To obtain a Live API Key, you must subscribe to any plan.

Payments are handled via M-Pesa.

3. Test Mode (Free)

Arifa provides one Test API Key:

Valid for 4 hours
One-time generation
For development only
Limited permissions

Generate here:

https://app.arifa.dev

Authentication & API Keys

Arifa uses API keys to identify your application.

Types of Keys

Type	Purpose	Expiration
Live Key	Production use	Never
Test Key	Development only	4 hours

Passing the API Key

API keys are included in:

WebSocket URL query parameters
HTTP POST body when sending notifications

Example (WebSocket URL)

wss://notifications.arifa.dev/ws/connect?api_key=YOUR_API_KEY&recipient=UUID&client=web or mobile

recipient must be a valid UUID v4.

WebSocket Connection

Arifa uses secure WebSocket (WSS) connections.

Connection Format

wss://notifications.arifa.dev/ws/connect?api_key=YOUR_API_KEY&recipient=UUID&client=web/mobile

Required Parameters:

Parameter	Description
api_key	Your Live or Test API Key
recipient	The user receiving notifications (UUID)
client	can be web or mobile based on the apikey type

Example in JavaScript

const ws = new WebSocket(
  "wss://notifications.arifa.dev/ws/connect?api_key=TEST_123&recipient=2fdb5a8e-62fc-4af2-9c41-807c3e9a8b17&client=web/mobile"
);

ws.onmessage = (msg) => {
  console.log("Received:", msg.data);
};

When WebSocket Opens

The user is considered online, and notifications will be delivered instantly.

Sending Notifications

Notifications are sent using a POST request.

Endpoint

POST https://notifications.arifa.dev/notify

Notes

If you are running this from a script, make sure to include the Origin header. The value must match the domain you registered when creating a web API key; otherwise, the request will be rejected.

Required JSON Body

{
  "recipient": "UUID_of_user",
  "payload": {   # Payload can be any JSON structure based on your need
    "title": "Hello",
    "body": "Welcome to Arifa!"
  },
  "api_key": "YOUR_API_KEY",
  "client" : <"web" or "mobile">
}

Notes

recipient → must be a valid UUID
payload → must be valid JSON
- The payload field can contain any JSON structure based on your needs — as long as it is valid JSON.
  - You can include custom keys
  - Nested objects
  - Arrays
  - Any format your application requires
api_key → must be included and valid
client → "web" or "mobile"

curl -X POST https://notifications.arifa.dev/notify \
  -H "Content-Type: application/json" \
  -H "Origin: http://localhost:5173" \ # The registred domain for the api key if web
  -d '{
    "recipient": "e3ec1c15-baf1-4ebf-82df-3d0b66ed9982",
    "payload": { "message": "Test" }, // Message can b
    "api_key": <API KEY>,
    "client" : "web"
  }'