Create Client

Before you can call any protected endpoint you need an API client. A client is the unit of identity that the integration service uses to attach IP allowlists, rate limits, monthly usage quotas, mTLS certificates, and the grant_types you are allowed to use.

Clients are provisioned out-of-band by the platform operator (admin / owner panel). This page documents the shape of a client so you know what to expect when one is handed to you, and which fields you need to plumb into your runtime.

Credentials You Will Receive

Field	Description
client_id	UUID-formatted identifier, e.g. c1a9beda-b14c-4eb5-b880-113023e6fc2d. Sent on every OAuth call.
client_secret	High-entropy secret. Sent on every OAuth call. Treat as a password — store in a secret manager.
Client certificate (optional)	When require_certificate = true the operator hands you a one-time certificate + private key bundle. The server only stores the public material and the SHA-256 fingerprint; the private key is never retrievable later.

Client-Level Guards

Every protected call passes through middleware that consults the client document for the following guards. Failing any of them returns a 4xx without reaching the business handler.

Grant Types (grant_types)

The OAuth grants the client is allowed to use. The token endpoint rejects any grant not listed here even if the parameters are otherwise valid. Supported values:

• password
• client_credentials
• refresh_token
• authorization_code (reserved — not currently wired into the token endpoint)

See Create a Token for per-grant request/response details.

Token Expiry (token_expiry)

Controls the lifetime of access tokens issued under the client-credentials grant.

Field	Type	Notes
enabled	boolean	When false, issued access tokens omit the exp claim. Refresh tokens are still subject to the absolute 365-day max-age cap.
duration	duration	When enabled = true, the access token's lifetime. Expressed in nanoseconds in the JSON representation (time.Duration).

The supervisor password grant uses fixed lifetimes (15 min access / 30 days refresh) and ignores this policy.

IP Allowlist (allowed_ips)

Flat list of literal IPs and/or CIDR blocks. Examples:

["203.0.113.42", "203.0.113.0/24", "2001:db8::/32"]

An empty list means "no restriction" — useful for development clients but discouraged in production. Requests from outside the allowlist are rejected with 403 by CheckIPAddress middleware.

Rate Limit (rate_limit)

Three concentric windows, all enforced per-client:

Field	Description
requests_per_second	Burst ceiling. First tier checked.
requests_per_minute	Smoothing ceiling. Checked only if the per-second window is not yet full.
requests_per_hour	Daily-budget guard. Checked after the per-minute window.

When any tier overflows the middleware returns HTTP 429 with Retry-After (seconds) and X-Ratelimit-Limit-* / X-Ratelimit-Remaining-* headers describing the breached tier.

Monthly Usage Limit (monthly_limit)

A separate quota measured in endpoint scores, not requests — every endpoint has a score (default 1000) and each call accrues that score against the running monthly total. See Usages / Score.

When the rolling monthly total would exceed monthly_limit the middleware returns HTTP 429 with X-MonthlyLimit-Limit, X-MonthlyLimit-Used, X-MonthlyLimit-Remaining. The counter is held in Redis under monthly-usage-{clientID}-{YYYY-MM} for fast reads and re-derived from MongoDB on cache miss.

mTLS (require_certificate, certificate, cert_fingerprint, cert_serial, cert_expires_at)

When require_certificate = true the integration's mTLS middleware compares the SHA-256 fingerprint forwarded by NGINX (ssl-client-fingerprint) against cert_fingerprint. Mismatches return 403 — including the case where the certificate is absent.

certificate stores the public PEM material only. The matching private key is delivered to the operator once through the create / regenerate response and never persisted server-side. Plan your secret-storage workflow with that in mind.

Pre-existing clients created before mTLS was introduced read require_certificate = false by default and continue to work without a certificate until the operator opts in.

Active Flag (is_active)

The operator can deactivate a client without deleting it. Inactive clients fail authentication immediately and skip all further middleware.

Operational Checklist

• Store client_id, client_secret and (if issued) the mTLS private key in a secrets manager. The private key is not recoverable after the create / regenerate response.
• Plumb your egress IP / CIDR into allowed_ips before going live in production.
• Pick a sensible token_expiry.duration for client-credentials clients — long-lived tokens reduce the chance of catastrophic revocation, short-lived tokens reduce blast radius if leaked.
• Monitor X-MonthlyLimit-Remaining in your client and proactively request a quota increase before the bucket empties — a 429 surfaces only after the limit has already been hit.
• Rotate client_secret and the mTLS certificate (/regenerate) on a schedule consistent with your internal policy.