Open Platform

API Client Application Access

Create API Clients, grant scopes, issue access tokens, and call Zenative public APIs from server-to-server integrations.

API Clients let an organization connect server-side systems to Zenative public APIs without using a human browser session. Use them for backend integrations, automations, sync jobs, and trusted services that need application access to organization-owned data.

An API Client is an organization-scoped application identity. It is not a user, does not inherit the role of the person who created it, and does not use OAuth delegated consent. Runtime access is controlled by the API Client’s own status, credentials, scopes, the organization’s active state, product capabilities, and the resource being requested.

When To Use API Clients

Use an API Client when:

• A backend service needs to call Zenative APIs without a signed-in human.
• The integration is owned by one organization.
• Access can be expressed with application scopes such as forms.read.
• The secret can be stored in a backend secret manager.

Do not use an API Client for browser-only apps, mobile apps, or untrusted clients that cannot keep a secret. Do not use an API Client when the external app must act on behalf of a specific human user; that is the OAuth delegated access model.

Create And Configure An API Client

In Workbench, open organization settings and go to API Clients.

1. Create an API Client with a clear display name, such as Warehouse Sync or Website Lead Importer.
2. Open the API Client detail page.
3. Grant only the scopes the integration needs.
4. Create a credential.
5. Copy the client secret immediately. It is shown only once.
6. Store the client ID and client secret in the integration’s backend secret manager.

API Client management is security-sensitive. Creating clients, changing scopes, creating or revoking credentials, disabling, reactivating, and deleting clients can require recent administrator verification.

Credential Material

Each API Client credential has two parts:

• clientId: a stable identifier for the credential, such as cred_....
• clientSecret: the secret value. Zenative shows it only once when the credential is created.

The client secret cannot be recovered later. If it is lost, create a new credential, update the integration, and revoke the old credential after the new one works.

Treat the secret like a password:

• Store it only in a backend secret manager.
• Do not place it in frontend code, mobile apps, logs, analytics, screenshots, support tickets, or crash reports.
• Prefer an expiration date when the integration can support planned rotation.
• Rotate credentials on a regular schedule and after any suspected exposure.

Issue An Access Token

API Clients do not call public APIs with the long-lived secret directly. First exchange the client ID and client secret for a short-lived access token.

Send a POST request to the organization’s API host:

curl -X POST "https://{organization-api-host}/api/v1/api-client-tokens" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n')"

The Basic authorization username is the client ID. The Basic authorization password is the client secret.

A successful response looks like this:

{
  "accessToken": "eyJ...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "expiresAt": "2026-06-16T10:15:00Z",
  "apiClientId": "1001"
}

Use the expiresIn or expiresAt value from the response. Do not assume a fixed token lifetime.

Token exchange can fail when the credential is wrong, expired, revoked, belongs to a different organization, the API Client is disabled or deleted, the organization is inactive, or the request is sent to the wrong organization host.

Call Public APIs

Use the returned bearer token on API Client-compatible endpoints:

curl "https://{organization-api-host}/api/v1/forms" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Do not send browser session cookies with API Client token exchange or bearer API requests. API Client authentication is intentionally separate from Workbench browser sessions.

Supported Scopes

Scopes are allow-list grants for API Client runtime access. They are not tenant roles and they do not bypass product capabilities, tenant state, or resource authorization.

If an endpoint is not listed for a scope, do not assume the scope grants access to it. New public API endpoints are exposed explicitly.

Lifecycle And Access Effects

API Client status controls all credentials and tokens for that client.

Credential status controls one credential at a time.

Use disable when you need to stop all access quickly. Use credential revocation when only one credential should stop working. Use delete when the integration should no longer be managed or used.

Common Errors

Zenative APIs return Problem Details for errors. Use the HTTP status, stable errorCode, and response correlationId for troubleshooting.

Security Checklist

• Create one API Client per integration or automation boundary.
• Grant the smallest set of scopes required.
• Keep production and test credentials separate.
• Store the secret in backend infrastructure, not in source code.
• Copy the secret only during creation and remove it from temporary notes.
• Rotate credentials before expiration.
• Revoke old credentials after rollout.
• Disable the API Client immediately when an integration is compromised.
• Delete API Clients that should no longer be managed or used.