Create Client

Before you can call any protected endpoint you need an API client. A client is the identity the integration service attaches your permissions, grant types, IP allow-list, rate limits, monthly usage quota, usage window and (optionally) client certificate to.

Clients are provisioned by the platform operator from the admin panel; there is no partner endpoint that creates one. This page describes what you receive and which client settings affect your calls.

Credentials you receive

Item	Description
client_id	UUID, for example c1a9beda-b14c-4eb5-b880-113023e6fc2d. Sent on every token request.
client_secret	High-entropy secret, sent on every token request. Treat it as a password and keep it in a secret manager.
Client certificate + private key	Only when the client requires a certificate. The private key is shown once at issue time. See mTLS Client Certificates.

Client settings that affect your calls

Every protected call passes through a chain of checks that read your client. A failure is refused before any business logic runs.

Grant types (grant_types)

The OAuth grants the client may use: client_credentials, password, refresh_token. The token endpoint refuses a grant that is not enabled on the client. See Create a Token.

Scopes (scopes)

The permissions a client_credentials token carries. Each endpoint page lists the permission it requires; a token without it is refused at the gateway with 403. Tokens issued with the password grant carry the supervisor's role permissions instead.

Token expiry (token_expiry)

Lifetime of tokens issued with the client_credentials grant: enabled and duration. When enabled is false the tokens carry no expiry (expires_in: 0); refresh tokens are still capped at 365 days. The password grant uses fixed lifetimes (15 minutes / 30 days).

A client has one live access token at a time: issuing a new one invalidates the previous one. See Create a Token.

Usage window (expires_at)

When set, the client stops issuing tokens after this time, with any grant (the token endpoint answers code 10004, client has expired).

IP allow-list (allowed_ips)

Literal IPs and/or CIDR blocks:

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

An empty list means no restriction. A call from an address outside a non-empty list is refused with 401. The allow-list applies to API calls; the token endpoint does not check it.

Rate limit (rate_limit)

Field	Description
requests_per_second	Checked first
requests_per_minute	Checked second
requests_per_hour	Checked third

A value of 0 disables that window. When a window overflows the call is refused with 429, code 10011, a Retry-After header and the breached window's headers, for example X-Ratelimit-Limit-Second / X-Ratelimit-Remaining-Second (likewise -Minute, -Hour).

Monthly usage limit (monthly_limit)

A monthly quota measured in endpoint scores, not requests. See Usages / Score. When the client has a monthly limit, every response carries X-Monthlylimit-Limit, X-Monthlylimit-Used and X-Monthlylimit-Remaining; when the quota is used up calls are refused with 429, code 10012, and Retry-After: 3600. 0 means no monthly limit (and no headers).

Client certificate (require_certificate)

When true, every call, including the token request, must present the certificate issued to the client during the TLS handshake. Failures answer 401. See mTLS Client Certificates.

Active flag (is_active)

The operator can deactivate a client without deleting it. An inactive client cannot obtain tokens (code 10002).

Operational checklist

• Store client_id, client_secret and, if issued, the certificate's private key in a secret manager.
• Give the operator your egress IPs / CIDRs for allowed_ips before going live.
• Let one process own the client's token, or use one client per process: a new token invalidates the previous one.
• Watch X-Monthlylimit-Remaining and ask for a quota increase before it reaches zero.
• Track the certificate's expiry and the client's expires_at, and ask the operator to renew them in time.