Equation

Appearance

Platform Administrator Guide ​

This guide is for Platform Administrators who manage the Equation API Management infrastructure. Platform Administrators are responsible for configuring the overall platform, managing access control, and ensuring secure, scalable API deployment.

Overview ​

The Platform Administrator role involves:

  • Configuring Azure API Management (APIM) infrastructure
  • Managing role-based access control (RBAC)
  • Onboarding new APIs and product teams
  • Ensuring security and compliance
  • Monitoring platform health

Core Responsibilities ​

Infrastructure Management ​

  • Architecture - Understanding the platform architecture
  • Add an API - Onboarding, support teams to add new APIs to the platform

Security & Access Control ​

Monitoring & Operations ​

  • Logging - Central logging and metrics

Quick Start ​

Onboarding a New API ​

  1. Product team creates a pull request with their API configuration
  2. Review the PR in the infrastructure repository
  3. Verify the configuration is correct
  4. Merge the PR to deploy
  5. The platform automatically assigns permissions to the team's managed identity

Managing User Access ​

For Developer Portal Access:

  1. Users must sign in to the developer portal at least once
  2. Users are automatically added to the default "developers" group, and can view APIs in calculation-api product
  3. (Optional) You can add users to custom groups to see others products via the infrastructure repository

For API Access: In most cases, API can be accessed according to the policies config, we not use subscriptions for now.

For Azure Resources:

  1. Use Azure RBAC to grant permissions to platform administrators
  2. Grant managed identities appropriate permissions for backend resources
  3. See Architecture for RBAC configuration

Architecture Overview ​

The Equation platform uses Azure API Management as a central gateway for all APIs. The architecture includes:

  • Calculation Layer: Python packages with business logic
  • API Layer: FastAPI/Django backends exposing the logic
  • Management Layer: Azure API Management for routing and policies
  • Client Layer: WaterFuser, Excel, Grasshopper, Python SDK

See the Architecture documentation for detailed information.

Common Tasks ​

Review a New API Pull Request ​

  1. Check the API configuration in terraform.tfvars
  2. Verify the managed identity exists
  3. Ensure backend URL and resource ID are correct
  4. Review policy configurations
  5. Approve and merge

Grant Custom Permissions ​

  1. Review the custom group request in groups_users.auto.tfvars
  2. Verify users have signed in to the developer portal
  3. Approve the group configuration
  4. Merge to apply changes

Troubleshoot Access Issues ​

  1. Check RBAC assignments in Azure Portal
  2. Verify managed identity has correct permissions
  3. Review APIM policy configurations
  4. Check logs in Azure Monitor

Best Practices ​

  • ✅ Use Infrastructure as Code (Terraform) for all changes
  • ✅ Review all pull requests before merging
  • ✅ Ensure teams use managed identities (not personal accounts)
  • ✅ Scope permissions tightly to prevent cross-team access
  • ✅ Monitor APIM logs regularly
  • ✅ Document custom configurations
  • ❌ Don't grant global permissions
  • ❌ Don't bypass the PR review process
  • ❌ Don't create manual configurations in Azure Portal

Support & Resources ​

Infrastructure Repository ​

Azure Resources ​

Contact ​

For platform administration questions or access requests, contact the Equation Platform team.