Authentication & API Keys

Arifa uses API keys to authenticate and identify your application when connecting to realtime services

Types of Keys

How to Use Your API Key

Your API key needs to be included in two places:

1. When connecting (in the WebSocket URL)

2. When sending notifications (in the HTTP request)

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

Parameters:

1. api_key - Your authentication key (required)

2. recipient - Target user UUID (required, must be valid UUID v4)

3. client - Client type: web or mobile (required)

Security Requirements

UUID Format Validation

The recipient parameter must adhere to UUID v4 format specifications:

• Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

• Version: 4 (indicated by the third group starting with '4')

• Variant: RFC 4122 (indicated by 'y' being 8, 9, A, or B)

• Examples:

  • Valid: 550e8400-e29b-41d4-a716-446655440000

  • Invalid: user-123, 12345678, 550e8400-e29b-11d4-a716-446655440000 (version 1)

Key Management Best Practices

• Store keys securely - Never commit API keys to version control

• Key rotation - Regularly rotate production keys

• Access control - Restrict key usage to authorized applications only

• Monitoring - Monitor API key usage for suspicious activity

Troubleshooting

Error Responses

• 429 Too Many Requests - Concurrent connection limit reached

• 401 Unauthorized - Invalid or missing API key

• 400 Bad Request - Invalid UUID format or missing required parameters

• 403 Forbidden - Insufficient permissions or rate limit exceeded