API Keys Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Sections
Settings Reference
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are API Keys?

API Keys is a REST API authentication module that manages tokens for programmatic access to the Ring2All API. Each key can be scoped to specific tenants/domains and optionally have an expiration date.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                API Keys Architecture                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  API Key Definition                                             │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        API Key: CRM Integration                          │   │
│  │                                                          │   │
│  │  Key: r2a_xxxx...xxxx (shown once)                      │   │
│  │  Prefix: r2a_                                           │   │
│  │  Scope: Tenant-specific (main)                          │   │
│  │  Domain: All Domains                                     │   │
│  │  Expires: 2025-12-31                                    │   │
│  │  Status: Active                                          │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Used in API requests                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        API Request                                       │   │
│  │                                                          │   │
│  │  GET /api/v1/extensions                                 │   │
│  │  Authorization: Bearer r2a_xxxx...xxxx                  │   │
│  │  X-Tenant-Slug: main                                    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Validated by                                           │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        API Gateway                                       │   │
│  │                                                          │   │
│  │  Checks:                                                 │   │
│  │  ├─ Key exists and active                               │   │
│  │  ├─ Key not expired                                     │   │
│  │  ├─ Tenant scope matches request                        │   │
│  │  └─ Domain scope matches (if restricted)                │   │
│  │                                                          │   │
│  │  Result: Allow or 401 Unauthorized                      │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.api_keys`	API key records

Key Files

File	Description
`modules/apiKeys/`	Frontend module

---

2. Module Overview (Commercial/Business)

Business Value

API Keys provides secure programmatic access:

Without API Keys	With API Keys
No automation	Full API access
Manual operations	Scripted workflows
No integrations	CRM/ERP integration
Password sharing	Secure tokens

Use Cases

Third-party Integration

- CRM systems

- Billing platforms

- Custom dashboards

Automation

- Provisioning scripts

- Bulk operations

- Scheduled tasks

Multi-tenant Access

- Global keys for system integrations

- Tenant-specific for isolated access

Security Compliance

- Expiration policies

- Key rotation

- Audit trail

Feature Highlights

Feature	Benefit
Secure Keys	One-time reveal
Tenant Scope	Global or specific
Domain Scope	Granular access
Expiration	Auto-disable old keys
Status Toggle	Enable/disable
Prefix	Identify key type

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create API keys for integrations
Set tenant scope (global or specific)
Restrict to specific domains
Set expiration dates
Enable/disable keys
Copy key on creation (one-time)
Track last usage

API Keys Interface

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              API Keys                                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [+ Create API Key]                                             │
│                                                                 │
│  [🔍 Search API keys...]                                        │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Name            │ Prefix  │ Scope    │ Expires  │ Status │  │
│  ├─────────────────┼─────────┼──────────┼──────────┼────────┤  │
│  │ CRM Integration │ r2a_abc │ main     │ 2025-12  │ Active │  │
│  │ Billing System  │ r2a_def │ Global   │ Never    │ Active │  │
│  │ Old Script      │ r2a_ghi │ branch   │ 2024-06  │ Expired│  │
│  │ Test Key        │ r2a_jkl │ main     │ Never    │ Inactive│ │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Create API Key

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Create API Key                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ▼ Basic Information                                            │
│                                                                 │
│  API Key Name: [CRM Integration              ]                 │
│    Unique name for identifying this API key                     │
│                                                                 │
│  Description: [Integration with Salesforce   ]                 │
│    Optional note describing the purpose                         │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  Tenant:                                                        │
│  ○ Global (All Tenants)                                        │
│      The API key can access every tenant.                       │
│  ● Tenant-specific                                             │
│      The API key can only access the selected tenant.          │
│                                                                 │
│  Select Tenant: [main ▼]                                       │
│                                                                 │
│  Domain Scope: [All Domains ▼]                                 │
│    When a tenant is selected, you can further restrict         │
│    access to a specific domain.                                 │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  Expiration: [2025-12-31    ]                                  │
│    Leave blank for a key without expiration.                    │
│                                                                 │
│  Active: ✓                                                     │
│    Disabled keys are rejected by the API.                       │
│                                                                 │
│  [Create API Key] [Cancel]                                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Generated Key (Shown Once)

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              🔒 Generated API Key                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  🔒 Your API Key (hover to reveal)                              │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ r2a_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0...         [📋]││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                 │
│  ⚠️ Important: This is the only time you will see this API key │
│  in full. Store it securely!                                    │
│                                                                 │
│  Usage: Authorization: Bearer r2a_a1b2c3d4e5f6g7h8...          │
│                                                                 │
│  [Close]                                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Copy Immediately: Key is shown only once during creation.

TIP

Use Expiration: Enforce key rotation for security.

WARNING

Store Securely: Keys cannot be retrieved after creation.

---

4. Configuration Sections

Basic Information

Field	Description
API Key Name	Unique identifier
Description	Purpose notes
Active	Enable/disable key

Scope Settings

Field	Description
Tenant	Global or specific tenant
Domain Scope	All domains or specific

Security Settings

Field	Description
Expiration	Optional expiration date

---

5. Settings Reference

Tenant Scope Options

Option	Description
Global	Access all tenants
Tenant-specific	Access one tenant only

Status Values

Status	Description
Active	Key is valid
Inactive	Manually disabled
Expired	Past expiration date

API Usage

Bash

# Request with API key
curl -X GET "https://api.ring2all.com/v1/extensions" \
  -H "Authorization: Bearer r2a_your_api_key_here" \
  -H "X-Tenant-Slug: main"

---

6. Common Scenarios & Examples

Scenario 1: Create Integration Key

Click "Create API Key"
Name = "CRM Integration"
Description = "Salesforce contact sync"
Scope = Tenant-specific, select tenant
Expiration = 1 year from now
Click Create
Copy the key immediately
Configure in CRM

Scenario 2: Global System Key

Click "Create API Key"
Name = "System Automation"
Scope = Global (All Tenants)
Expiration = None
Create and copy key

Scenario 3: Disable Old Key

Find key in list
Click Edit
Uncheck "Active"
Save

Scenario 4: Key Rotation

Create new key (same purpose)
Update integration with new key
Verify new key works
Delete old key

---

7. Limitations & Important Notes

Technical Notes

NOTE

One-time Display: Key shown only at creation.

NOTE

Cannot Retrieve: Lost keys require new key creation.

WARNING

Secure Storage: Store keys in secure credential managers.

Best Practices

Unique Keys: One key per integration
Descriptive Names: "CRM_Salesforce_Prod"
Set Expiration: Enforce rotation
Least Privilege: Tenant-specific when possible
Rotate Regularly: Replace keys periodically

Security Recommendations

Practice	Description
Key Rotation	Replace keys every 90 days
Environment Vars	Don't hardcode keys
Audit Usage	Monitor last used dates
Disable Unused	Deactivate unused keys

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
401 Unauthorized	Key inactive	Check status
401 Unauthorized	Key expired	Create new key
403 Forbidden	Wrong tenant	Check scope
Key lost	Not saved	Create new key

Test API Key

Bash

# Verify key works
curl -I "https://api.ring2all.com/v1/health" \
  -H "Authorization: Bearer r2a_your_key"

# Expected: HTTP 200 OK

Check Key in Database

Sql

SELECT 
  name,
  prefix,
  tenant_scope,
  is_active,
  expires_at,
  last_used_at
FROM public.api_keys
WHERE name = 'CRM Integration';

---

9. Glossary

Term	Definition
API Key	Authentication token
Bearer Token	Authorization header format
Tenant Scope	Access restriction
Prefix	Key identifier (r2a_)
Expiration	Auto-disable date
Key Rotation	Regular key replacement

---

Lua Script Status ℹ️

Admin Module

Component	Status
API Keys	ℹ️ REST API authentication - no Lua handler required

API Keys is an administration module. Keys authenticate REST API requests. No Lua handlers are used - authentication is handled by the backend API middleware.

---

Documentation last updated: January 2026

API Keys Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are API Keys?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

API Keys Interface

Create API Key

Generated Key (Shown Once)

Quick Tips

4. Configuration Sections

Basic Information

Scope Settings

Security Settings

5. Settings Reference

Tenant Scope Options

Status Values

API Usage

6. Common Scenarios & Examples

Scenario 1: Create Integration Key

Scenario 2: Global System Key

Scenario 3: Disable Old Key

Scenario 4: Key Rotation

7. Limitations & Important Notes

Technical Notes

Best Practices

Security Recommendations

8. Troubleshooting Tips

Common Issues

Test API Key

Check Key in Database

9. Glossary

Lua Script Status ℹ️

Admin Module