Authentication

Authentication modes for the Angage Marketplace API

Overview

The Angage Marketplace uses different authentication modes for different surfaces: web users authenticate via SSO with angage.id; the /api/v1 platform endpoints authenticate via a pre-shared API key; and webhook endpoints authenticate via HMAC signatures.

Platform API Key

Primary authentication for /api/v1 platform endpoints.

  • Header: X-Platform-Api-Key: YOUR_KEY
  • Configured in the ERP via the MARKETPLACE_API_KEY environment variable
  • Keys are rotated via admin operations
  • The server uses a timing-safe comparison (hash_equals()) when verifying keys
GET /api/v1/tenant/extensions HTTP/1.1
Host: marketplace.angage.com.au
X-Platform-Api-Key: pk_live_xxxxxxxxxxxx
X-Tenant-Id: tenant-abc-123

Webhook Signature Verification

All webhook requests must include the X-Webhook-Signature header containing an HMAC-SHA256 digest of the raw request body using a shared secret.

  • Header: X-Webhook-Signature: sha256=...
  • The shared secret is configured per integration
  • The server uses hash_hmac('sha256', $rawBody, $secret) for verification
  • The signature is computed over the RAW request body (not re-encoded JSON)

SSO (angage.id)

End-user authentication for the marketplace web UI.

  • Users click "Sign in" and are redirected to angage.id OAuth
  • The OAuth callback returns an access token plus user info
  • Session stores sso_id, email, and tenant_id
  • SSO is for WEB users, not for API consumers
  • Extensions do not use SSO to call the marketplace API

Developer Portal Auth

Developers log into the developer portal with email and password (or via SSO). Routes under /developer/* are protected by the developer guard. This is separate from platform API auth.

What NOT to Use

  • There is no public developer API key — developers manage extensions via the web portal.
  • There is no OAuth 2.0 flow for third-party clients to call /api/v1.
  • There is no session-cookie auth for /api/v1 endpoints.