Authentication

Table of Contents

Dual-Layer Authentication System

The RCAMS API uses a dual-layer authentication system for enhanced security. This ensures that only authorized personnel can access and control the emergency notification system.

Authentication Layers
Basic Authentication

API credentials that grant access to the API itself. These are provided by the RCAMS administrator to authorized integrators.

Basic Authentication

All API requests must include a Basic Authentication header with API credentials. These credentials will be initially provided manually by the RCAMS administrator to authorized integrators. They are not user-specific but rather grant access to the API itself.

Required Credentials
  • Username: <api_username>
  • Password: <api_password>
HTTP Header Format
Authorization: Basic <base64_encoded_credentials>

Note: The authorization header is created by base64-encoding the string <api_username>:<api_password> and prefixing it with Basic .

JavaScript Example: Creating Basic Auth Header
// Replace with actual API credentials provided by the administrator
const apiUsername = 'your_api_username';
const apiPassword = 'your_api_password';

// Create the base64-encoded credentials
const encodedCredentials = btoa(`${apiUsername}:${apiPassword}`);

// Create the authorization header
const authHeader = `Basic ${encodedCredentials}`;

// Use in fetch requests
fetch('https://rcamsapi.spheronomics.com/api/v2/endpoint.php', {
    method: 'POST',
    headers: {
        'Authorization': authHeader
    },
    // Other request options...
});

Authentication Flow

The complete authentication flow for using the RCAMS API is as follows:

  1. Obtain API credentials (username and password) from your RCAMS administrator
  2. Create a Basic Authentication header using these credentials
  3. Include the Basic Auth header in all subsequent API requests
  4. When finished, call the logout endpoint to invalidate the user login
Authentication Flow Diagram
┌─────────────┐      ┌────────────┐      ┌──────────────────┐
│  Obtain API  │      │ Create Basic│      │ Call login.php   │
│  Credentials │─────▶│  Auth Header│─────▶│ with user creds  │
└──────────────┘      └────────────┘      └────────┬─────────┘
                                                   │
                                                   ▼
                     ┌────────────┐      ┌─────────────────┐
                     │ Include    │      │ Make API        │
                     │ Basic Auth │◀─────│ Requests        │
                     │ in all API │      └────────┬────────┘
                     │ requests   │               │
                     └────────────┘               │
                                                  ▼
                                          ┌───────────────┐
                                          │ Complete      │
                                          │ Session       │
                                          └───────────────┘

Login Endpoint

Authenticates a user.

POST/login.php

Authenticates a user.

Request Parameters
Parameter Type Required Description
user String Yes User's email address
pass String Yes User's password
Response

On successful authentication, the server returns a success login.

Example Response (Success)
{
  "status": "OK",
  "message": "Login successful"
}
Example Request (JavaScript)
// Set up the request
const formData = new FormData();
formData.append('user', 'admin@example.com');
formData.append('pass', 'password123');

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/login.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password') // Replace with actual API credentials
  },
  body: formData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    localStorage.setItem('rcams_user', api_username);
    localStorage.setItem('rcams_pass', api_password);
    console.log('Login successful!');
  } else {
    console.error('Login failed:', data.message);
  }
})
.catch(error => {
  console.error('Error:', error);
});

Logout Endpoint

Invalidates the current authentication user.

POST/logout.php

Logout the current user.

Request Parameters
None
Response

On successful logout, the server confirms the user has been logged out.

Example Response (Success)
{
  "status": "ok",
  "message": "Logout successful"
}
Example Request (JavaScript)
// Set up the request
const formData = new FormData();

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/logout.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password') // Replace with actual API credentials
  },
  body: formData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'ok') {
    // Clear stored data
    localStorage.removeItem('rcams_user');
    localStorage.removeItem('rcams_pass');
    console.log('Logout successful!');
  } else {
    console.error('Logout failed:', data.message);
  }
})
.catch(error => {
  console.error('Error:', error);
});

Error Handling

The authentication endpoints may return different error responses that your application should handle appropriately.

Common Authentication Error Responses
Invalid Basic Authentication
{
  "status": "denied",
  "message": "Authorization denied"
}
Invalid User Credentials
{
  "status": "denied",
  "message": "Invalid credentials."
}
Missing Required Parameters
{
  "status": "false",
  "message": "missed_params"
}

Security Best Practices

Authentication Security Best Practices
  • Secure Credential Storage - Store API credentials securely, never expose them to end users or client-side code.
  • HTTPS Only - Always use HTTPS for all API calls to ensure data is encrypted in transit.
  • Logout on Session End - Always invalidate users when a user session ends for enhanced security.
  • Error Handling - Implement proper error handling for authentication issues.
  • Minimal Permissions - Use accounts with only the necessary permissions required for the integration.
Introduction Districts Management