Skip to main content

Clients

A Client represents any application, service, or person that calls your APIs through Zerq. Create a client for each distinct consumer: a mobile app, a partner service, an internal microservice, or an AI agent.

Creating a Client​

  1. Go to Clients in the sidebar
  2. Click New Client
  3. Fill in the details:
FieldDescription
NameIdentifying name (e.g., "Acme Corp App", "Internal Analytics Service")
DescriptionOptional notes about this client
EmailContact email for this client
CollectionsWhich API collections this client can access
PolicyRate limit policy to apply (optional)
Developer Portal accessWhether this client can sign in to the Developer Portal
Authorized emailsEmail addresses allowed to sign in to the portal (if portal access is enabled)
  1. Click Create

A default access Profile is automatically created for the client with token authentication.

Managing collection access​

The most important setting is which collections the client can access. A client can only call endpoints within its assigned collections.

To update collection access:

  1. Open the client
  2. Click Edit
  3. Check/uncheck collections
  4. Save

Changes take effect immediately on the next request.

Client status​

Toggle a client between active and inactive:

  • Active: can make API calls
  • Inactive: all requests are rejected with 403 Forbidden

Use inactive status to temporarily suspend a client without deleting it.

Developer Portal access​

The Developer Portal uses a managed access model — there is no self-service registration. You must explicitly grant access for a client and list the authorized email addresses.

Enabling portal access​

  1. Open the client and click Edit.
  2. Toggle Developer Portal access to On (hasPortalAccess: true).
  3. Note: This toggle is independent of the client's active flag. A client can be active for API access but still have portal access disabled.
  4. Click Save.

Authorized emails​

The Authorized emails list controls which email addresses can request a magic-link login for this client:

  • Add the primary email (already set on the client) plus any additional emails.
  • Each authorized email can independently request a magic link.
  • Emails not on the list cannot sign in, even if they know the portal URL.
  • Add or remove emails at any time — changes take effect immediately.

Example: a client representing "Acme Corp" might have:

All three can sign in to the portal and see the same Acme Corp collections.

Once logged in, portal users see only the collections assigned to this client.

Viewing a client's profiles​

Each client can have multiple Profiles — different authentication configurations. Open a client and navigate to Profiles to manage them.

→ See Profiles

Editing and deleting​

  • Edit: Update name, description, email, collection access, policy, or portal settings
  • Delete: Permanently removes the client and all its profiles. All active API calls from this client will fail immediately.

Client ID​

Every client has a system-generated Client ID (UUID). This is the value clients send in the X-Client-ID header with every request. The Client ID is visible in the client detail view.

Quota tracking​

If a policy with a quota is attached, Zerq tracks the client's usage against the quota limit. You can see the current usage on the client detail page.