Overview
The Alertly Embed API allows you to integrate alert management directly into your SaaS application.
Your customers can manage their contacts, alert rules, and view alerts without leaving your platform.
Key features:
- White-label - Custom branding with your colors and logo
- Secure - JWT-based authentication with domain restrictions
- Flexible - Choose which features to expose (contacts, rules, alerts)
- Responsive - Works on desktop and mobile devices
Business Plan Required: The Embed API is available on the Business plan.
Quick Start
Get started with embedding Alertly in 3 simple steps:
1. Configure Embed Settings
Go to Dashboard → Settings and configure your embed settings:
- Add your domain to the allowed domains list
- Customize the primary color to match your brand
- Select which features to enable
2. Generate an Embed Token
Create a token for your user either via the dashboard or programmatically:
POST /embed/api/token/
Authorization: ApiKey your_api_key
{
"permissions": {
"contacts": true,
"rules": true,
"alerts": true
},
"external_user_id": "user-123",
"expires_in_hours": 24
}
3. Embed the Iframe
Add the iframe to your application:
<iframe
src="https://alerts.aiforsite.io/embed/contacts/?token=YOUR_TOKEN"
width="100%"
height="600"
frameborder="0"
></iframe>
Authentication
Embed tokens are JWTs signed with your tenant's unique secret. Tokens contain the tenant ID,
permissions, and expiration time.
Token Structure
The decoded token payload contains:
{
"tenant_id": "uuid-of-tenant",
"external_user_id": "your-user-id",
"permissions": ["contacts", "rules", "alerts"],
"exp": 1706400000,
"iat": 1706313600,
"type": "embed"
}
Security Note: Never expose your API key or embed secret in client-side code. Generate tokens on your backend.
Embed Settings
Configure embed settings in the dashboard or via the API:
| Setting |
Description |
Default |
allowed_domains |
Domains allowed to embed (supports wildcards like *.example.com) |
Empty (none allowed) |
primary_color |
Hex color for buttons and links |
#6366f1 |
logo_url |
URL to your logo image |
None |
hide_branding |
Hide "Powered by Alertly" footer |
true |
allow_contacts |
Enable contacts management view |
true |
allow_rules |
Enable alert rules view |
true |
allow_alerts |
Enable alerts list view |
true |
Custom Branding
Customize the embed appearance to match your application. The primary color is applied to:
- Primary buttons
- Links and interactive elements
- Focus states and highlights
- Badges and status indicators
Permissions
Control what your users can access by specifying permissions when generating tokens:
| Permission |
Description |
Allows |
contacts |
Contact management |
View, add, edit, delete contacts |
rules |
Alert rules |
View and create alert rules |
alerts |
Alerts list |
View alerts and filter by status/level |
Generate Token API
Endpoint
POST /embed/api/token/
Authentication
Use your API key in the Authorization header:
Authorization: ApiKey your_api_key
Authorization: Bearer your_api_key
Request Body
| Parameter |
Type |
Description |
permissions optional |
object |
Object with contacts, rules, alerts boolean flags |
external_user_id optional |
string |
Your application's user ID (for tracking) |
expires_in_hours optional |
integer |
Token expiration in hours (default: 24) |
Response
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"expires_in_hours": 24,
"permissions": ["contacts", "rules", "alerts"]
}
Embed Views
Three embeddable views are available:
Contacts View
/embed/contacts/?token=YOUR_TOKEN
Allows users to manage notification contacts - add, edit, and delete contacts with email and SMS preferences.
Rules View
/embed/rules/?token=YOUR_TOKEN
Configure alert rules with matching criteria, notification methods, reminders, and escalation settings.
Alerts View
/embed/alerts/?token=YOUR_TOKEN
View alerts with filtering by status (active, acknowledged, resolved) and level (critical, alarm, warning, info).
Iframe Integration
Basic Integration
<iframe
src="https://alerts.aiforsite.io/embed/contacts/?token=TOKEN"
width="100%"
height="600"
frameborder="0"
allow="clipboard-write"
></iframe>
Responsive Container
<div style="position: relative; height: 600px;">
<iframe
src="https://alerts.aiforsite.io/embed/contacts/?token=TOKEN"
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;"
></iframe>
</div>
Security Best Practices
- Generate tokens server-side - Never expose your API key in client code
- Use short token expiration - Default 24 hours is recommended
- Restrict domains - Only allow your application's domains
- Regenerate secrets if compromised - Use the dashboard to generate a new embed secret
- Use HTTPS - Always serve your application over HTTPS
Code Examples
Node.js / Express
const axios = require('axios');
app.get('/embed-token', async (req, res) => {
const response = await axios.post(
'https://alerts.aiforsite.io/embed/api/token/',
{
permissions: { contacts: true, rules: true, alerts: true },
external_user_id: req.user.id,
expires_in_hours: 24
},
{
headers: { 'Authorization': `ApiKey ${process.env.ALERTLY_API_KEY}` }
}
);
res.json({ token: response.data.token });
});
Python / Django
import requests
def get_embed_token(request):
response = requests.post(
'https://alerts.aiforsite.io/embed/api/token/',
json={
'permissions': {'contacts': True, 'rules': True, 'alerts': True},
'external_user_id': str(request.user.id),
'expires_in_hours': 24
},
headers={'Authorization': f'ApiKey {settings.ALERTLY_API_KEY}'}
)
return JsonResponse({'token': response.json()['token']})
PHP / Laravel
use Illuminate\Support\Facades\Http;
public function getEmbedToken(Request $request)
{
$response = Http::withHeaders([
'Authorization' => 'ApiKey ' . config('services.alertly.key')
])->post('https://alerts.aiforsite.io/embed/api/token/', [
'permissions' => ['contacts' => true, 'rules' => true, 'alerts' => true],
'external_user_id' => auth()->id(),
'expires_in_hours' => 24
]);
return response()->json(['token' => $response->json('token')]);
}