Manage API Keys and Webhook Keys

Overview

Use this guide to manage external integration credentials. Both API keys and webhook endpoints are managed directly in the SchoolBanks web admin experience.

Prerequisites

• Admin access to Admin > Settings.
• apikeys.read to view API keys.
• apikeys.create, apikeys.rotate, or apikeys.revoke for the matching API key action.
• webhooks.read to view webhook endpoints; webhooks.manage to create, toggle, delete, or test them.
• A secure place to store new secret values before generating or rotating credentials.

Step-by-step procedure

1. Open Admin.
2. Open Settings.
3. Select API Keys (/Admin/ApiKeys) to manage tenant API credentials.
4. In Create API Key, enter Client Name and optionally Expires At.
5. Select Generate Key.
6. Copy the generated key immediately. The secret value is intended to be shown only during creation or rotation.
7. Review Active Keys to confirm the client, expiration, and status.
8. Use Rotate when replacing an active credential.
9. Use Revoke when a credential should no longer be accepted.
10. Review Revoked / Inactive Keys when confirming that old access was removed.
11. Return to Settings and select Webhook Keys (/Admin/Webhooks) when webhook endpoint management is needed.
12. On the Webhooks page, use Create Webhook Endpoint, Target Url, Max Retries, Test, Disable, Enable, and Recent Deliveries to configure and validate webhook delivery. Disable or enable endpoints as needed during rollout or maintenance.

Variations / branching flows

• Planned rotation: generate or rotate the key, update the external system, validate traffic, then revoke the prior credential.
• Emergency revocation: revoke the key first, then coordinate a replacement with the integration owner.
• Webhook delivery validation: use Test before enabling a new endpoint for production events.
• Webhook pause: disable the endpoint during receiving-system maintenance, then enable it again after a successful test.

Expected outcomes

• New API keys appear in Active Keys with the expected client name and expiration.
• Rotated keys work for the external caller, while the replaced secret no longer works.
• Revoked keys move to Revoked / Inactive Keys and no longer authenticate API calls.
• Webhook endpoints can be tested and their recent delivery results are visible in Recent Deliveries.

Troubleshooting / edge cases

• If Generate Key, Rotate, or Revoke is unavailable, confirm the admin role includes the matching API key permission.
• If /Admin/Webhooks does not show endpoints, confirm the admin role includes webhooks.read.
• If a webhook test fails, validate the target URL, TLS certificate, firewall rules, receiver availability, and expected signing-secret handling.
• If an integration still works after revocation, confirm it is not using another active key for the same client.
• If the secret was not copied when shown, rotate the credential and store the replacement securely.

Related processes

• Configure Tenant Settings and Options
• SIEM Configuration Guide

Assumptions and gaps

• Webhook secret display behavior follows the same secure-handling expectation as API keys: copy new secrets at creation or rotation time.