Authentication Reference

API Keys, Headers & Scopes

Every request to the Envelark API must be authenticated using an active production or sandbox API key. Keys are provisioned with granular capability scopes to enforce the principle of least privilege.

1. Key Format & Generation

Envelark API keys are cryptographically generated using 48 lowercase hexadecimal characters (24 random bytes) from secure entropy via Crypto::generateApiKey(). Production keys begin with the prefix elv_live_ followed by the hex secret. For backward compatibility with earlier integrations, the authentication validator (Auth::attemptApiKey()) also accepts the legacy env_live_ prefix alias and normalizes between both prefixes during lookup.

Key Pattern Specification (Prose Summary):

A standard production key consists of the 9-character prefix (elv_live_, or the legacy alias env_live_) concatenated with 48 hexadecimal characters ([0-9a-f]), or 32 hexadecimal characters for initial seeded workspace keys. In all code samples below, replace the placeholder YOUR_API_KEY with your workspace credential.

How to Create API Keys

  1. Log into your Envelark workspace and navigate to the Developer console (sign in) (or Superadmin portal under /admin).
  2. Under Active API Credentials, your default live production key is ready for immediate relay.
  3. To configure new application credentials or custom webhook listeners, register a developer client with your desired capability scopes.

2. Authentication Header

Pass your API key using the standard HTTP Authorization header with the Bearer scheme. Alternatively, the custom headers X-Envelark-Api-Key and X-Api-Key are accepted by ApiController::authenticateApiRequest():

# Recommended: Bearer token header
Authorization: Bearer YOUR_API_KEY

# Alternate 1: Envelark custom API key header
X-Envelark-Api-Key: YOUR_API_KEY

# Alternate 2: Standard custom API key header alias
X-Api-Key: YOUR_API_KEY

3. Verified Capability Scopes

Every scope corresponds directly to capability definitions in the platform backend. The following scopes exist in the codebase:

Scope Name Granted Capabilities
mail.read Read mailboxes, query email threads, fetch thread messages, read smart category classifications, and view folder states.
mail.write Dispatch outbound email, execute transactional email sending, mutate thread workflow status, star/archive threads, and assign tickets.
mail.send Permission to invoke SMTP/Relay transactional email sending (aliased to mail.write for transactional pipelines).
files.read Inspect attachment metadata, verify SHA-256 fingerprints, and download files from the Elept cloud storage vault.
files.write Authorize file uploads to Elept Cloud, create persistent live ZIP packages (Elept Rooms), and heal storage references.
templates.read Fetch standard SaaS built-in developer templates (password reset, account verify, receipt, security alert) and custom workspace templates.
templates.write Create, edit, compile dynamic preview variables, and delete transactional HTML templates.
webhooks.manage Register destination webhook URLs, rotate HMAC SHA-256 secrets, and trigger synthetic test webhook deliveries.

4. Rate Limiting & Error Responses

To ensure high availability and prevent resource exhaustion, the API controller enforces an algorithmic sliding-window rate limit using RateLimiter::enforce('api_v1', $clientIdentifier, 120, 60):

  • Ceiling: 120 requests per 60-second window per client identifier.
  • Exceeded Response: HTTP 429 Too Many Requests with structured error envelope via Response::error().
// HTTP 429 Too Many Requests Response
{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too Many Requests. Rate limit exceeded.",
    "details": []
  }
}

Standard API Error Codes

All API error responses use the standard envelope {"success": false, "error": {"code": "...", "message": "...", "details": [...]}} emitted by Response::error() (app/core/Response.php:27-37):

Error Code HTTP Status Source (file:line) Description
empty_body 400 ApiController.php:275, 338 Empty request body on inbound webhook endpoint.
invalid_signature 400 ApiController.php:298 Inbound webhook HMAC signature verification failed.
webhook_error 400 ApiController.php:305 Inbound webhook payload processing error.
webhook_verification_failed 400 ApiController.php:353 Inbound Elept webhook signature verification failed.
update_failed 400 ApiController.php:716 Thread category mutation failed.
unauthorized 401 ApiController.php:51, 65 Invalid, expired, or missing API key / bearer token.
missing_signature 401 ApiController.php:293, 344 Missing webhook signature header on inbound webhook endpoint.
forbidden 403 ApiController.php:74, 114, 161, 167, 432 Access to specified mailbox/thread denied or protected system template.
not_found 404 ApiController.php:129, 396 Requested thread or template ID/slug does not exist.
route_not_found 404 Router.php:129 Requested API endpoint path or HTTP method does not match any registered route.
invalid_input 422 ApiController.php:146, 185, 368, 421, 572 Missing or invalid required request parameters (e.g., to, subject, name, body_html, or content).
delivery_failed 422 ApiController.php:456 Transactional template validation failed (to and template/html required) or message dispatch failed.
rate_limit_exceeded 429 ApiController.php:31 Client exceeded 120 requests per 60-second window.
internal_server_error 500 p/index.php:66 Unhandled server exception on an /api/* route.

5. Real Endpoint Examples

A. Fetch Mailboxes (GET /api/v1/mailboxes)

curl -X GET https://envelark.com/api/v1/mailboxes \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (HTTP 200 OK — serialized by MailboxService::getUserMailboxes() / getSampleMailboxes(), app/services/MailboxService.php:66-77, 1189-1233):

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "id": 1,
      "organization_id": 1,
      "name": "Support Team",
      "email_address": "support@example.com",
      "type": "hosted",
      "provider": "envelark_hosted",
      "color": "#0EA5E9",
      "unread_count": 3,
      "sync_status": "healthy",
      "last_synced_at": "2026-10-23 12:00:00"
    }
  ]
}

B. Dispatch Transactional Template (POST /api/v1/send)

curl -X POST https://envelark.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "password_reset",
    "to": "alex@example.com",
    "sender_name": "Acme Security",
    "sender_email": "security@example.com",
    "reply_to": "support@example.com",
    "variables": {
      "user_name": "Alex",
      "reset_url": "https://example.com/auth/reset?token=xyz987",
      "expiry_minutes": "30"
    },
    "branding": {
      "company_name": "Acme Corp",
      "primary_color": "#152E22"
    }
  }'

Response (HTTP 201 Created — serialized by TemplateService::sendTransactional(), app/services/TemplateService.php:771-784, and ApiController::sendTransactional(), app/controllers/Api/ApiController.php:438-461):

{
  "success": true,
  "message": "Transactional email dispatched.",
  "data": {
    "success": true,
    "message_id": "<3b68bc0974099c381f845e53463943c3@envelark.com>",
    "to": "alex@example.com",
    "subject": "Reset your password for Acme Corp",
    "template": "password_reset",
    "sent_at": "2026-10-23 12:00:00",
    "provider": "envelark_transactional_relay"
  }
}