API Clients

An “API client” in ActiveManage terminology is a registered external system that calls into the platform's API. Registering clients gives you visibility, observability, rate-limit isolation, and per-client revocation — all valuable when you have more than one integration.

What a Client Represents

• An external service that calls your API repeatedly (e.g. nightly Salesforce sync).
• A native app distributed to many devices (a mobile app's backend identity).
• A third-party integration that authenticates via OAuth.
• A development environment that needs sandboxed credentials.

Why Register Clients

• Observability: Per-client logs and usage charts.
• Per-client rate limits: Isolate spiky integrations from each other.
• Per-client scopes: Hard limit on what each integration can do.
• Revocation: Disable one integration without affecting others.
• Compliance: Demonstrate which systems were calling at audit time.

Worked Examples

• Salesforce client: Read+write on Customers, Orders. Rate limit 1000/min. Source IP locked to Salesforce egress range.
• Mobile app backend: Read+write on user-owned records. 10000/min rate limit. Identifies the mobile traffic separately from web.
• Third-party Slack bot: Read-only on notifications. OAuth-driven. Can be revoked by the user from their settings page.
• Internal data warehouse: Read-only across all datastores. Bulk endpoints allowed.

This article walks through registering a new API client. After this you'll have credentials to give the integration plus admin tools to observe and constrain it.

Step-by-Step

1. Open Architect Panel → API Clients and click New Client.
2. Name and description — be descriptive (“Salesforce Production”, not “sync”).
3. Pick auth mode:
   • API key for service-to-service.
   • OAuth for user-authorised third-party apps.
4. Select scopes — list each endpoint family the client may use, and read/write/admin for each.
5. Optional restrictions:
   • Allowed source IPs / CIDR ranges.
   • Rate-limit tier (default, elevated, custom).
   • Webhook URL — events fire to this URL when relevant records change.
6. Generate credentials. Copy them immediately; the secret is shown once.

Per-Client Configuration Worth Setting

• Idle timeout: Disable client if no calls in 30 days.
• Allowed endpoints: Whitelist beyond scopes — fine-grained access to specific paths only.
• Audit channel: Where the per-client log goes (file, Slack, Splunk).

Worked Examples

• Marketing CRM: Scopes: read+write on Contacts and Email Templates. IP-locked. 5000/min rate. Webhook fires on contact updates so the CRM stays in sync.
• Public OAuth app: Scopes: read on user's own records only. Anyone can authorise; each user controls their own grant.
• Internal tooling: Scopes: admin on everything. IP-locked to office VPN. Rate limit elevated.

Every call from a registered API client is logged. The logs are essential for debugging integration issues, monitoring abuse, and demonstrating compliance.

What's Captured

• Timestamp — to the millisecond.
• Client — which registered client made the call.
• Endpoint and method — e.g. POST /api/v1/records/orders.
• Status code — HTTP response (200, 404, 429, 500).
• Response time — milliseconds end-to-end.
• IP address — the calling source.
• Bytes in/out — payload sizes.
• Error details — on non-2xx responses, the error body is captured (PII-scrubbed).

Useful Filters

• Status code ≥ 400 — see all failed calls.
• Response time > 1000ms — find slow endpoints.
• Per client — drill into one integration.
• Per endpoint — see which endpoints get the most traffic.

Worked Examples

• Integration debugging: Customer reports their sync isn't picking up new orders. Filter by their client, sort by timestamp — see that GET /orders is returning empty even though there are new orders. Check their query parameters.
• Rate limit investigation: Filter status=429 — see which clients are bumping the limit and at what endpoints.
• Slow endpoint detection: Sort by response time descending — top results identify slow endpoints needing optimisation.
• Abuse detection: Spike in 401s suggests credential trouble; spike in 403s suggests over-eager scope; spike in 500s suggests bug.

Note: Logs are retained 90 days by default. Configure longer retention if compliance requires; consider exporting to an external log store for years-long retention.