Skip to main content

Quickstart

This guide walks you through your first end-to-end flow on Zerq: publish an API, create a client with credentials, and make a live authenticated request — all in under 10 minutes.

Prerequisites: Zerq is deployed and you have access to the Management UI. If you need deployment help, contact your platform administrator.

Step 1 — Sign in to the Management UI​

Open your Zerq Management UI URL (e.g. https://zerq.yourdomain.com) and sign in with your platform credentials.

You land on the Dashboard, which shows request metrics, top endpoints, and recent activity.

Step 2 — Create a Collection​

A Collection is a logical group of API endpoints that share a base path, credentials, and access settings.

  1. In the sidebar, click Collections.
  2. Click New Collection.
  3. Fill in:
    • Name — a descriptive label (e.g. Payment API)
    • Base Path — the URL prefix for all endpoints in this collection (e.g. /payments)
    • Target Base URL — the upstream service this collection proxies to (e.g. https://api.payment-service.internal)
  4. Click Save.

The collection is created in Draft status. Nothing is published yet.

Step 3 — Add a Proxy (endpoint)​

A Proxy defines a single route — it maps an inbound path pattern to a target path on the upstream.

  1. Open the collection you just created.
  2. Click Add Proxy.
  3. Use the setup wizard:
    • Step 1 — Info: Enter a name and description for this endpoint.
    • Step 2 — Route: Set the HTTP method (e.g. GET) and path (e.g. /v1/charge). This path is appended to the collection base path.
    • Step 3 — Headers: Add any static or environment-variable-backed headers to forward upstream.
    • Step 4 — Parameters: Define path and query parameters with types and descriptions.
    • Step 5 — Schema: Add JSON Schema for request/response bodies (used in portal docs and OpenAPI export).
    • Step 6 — Review: Confirm and save.
  4. Click Publish on both the proxy and the collection to make them live.
tip

You can also import a complete OpenAPI 3.0/3.1 spec using Import → OpenAPI to bulk-create proxies.

Step 4 — Create a Client and Profile​

Clients represent the applications or teams that consume your APIs. Profiles hold the authentication credentials issued to a client.

Create a Client​

  1. Go to Access Control → Clients.
  2. Click New Client.
  3. Enter a Name and Email (the primary contact).
  4. Assign the client to your collection.
  5. Click Save.

Create a Profile​

  1. Open the client and click Add Profile.
  2. Enter a profile name (e.g. Production).
  3. Choose an authentication method:
    • Token — Zerq issues a bearer token. Best for server-to-server calls.
    • JWT — Client presents a short-lived HMAC-signed JWT.
    • OIDC — Client authenticates via your identity provider (e.g. Keycloak).
    • mTLS — Certificate-based mutual authentication at the gateway.
    • None — Open access (use only for internal or public endpoints).
  4. Click Save. The profile credentials are displayed — copy the token now, it won't be shown again.
note

The profile page shows token expiry state:

  • Valid (green) — token is active
  • Expiring Soon (amber) — expires in less than 24 hours
  • Expired (red) — rotate immediately

Step 5 — Make your first API call​

With the collection published and a profile token in hand, make a live request through the gateway.

curl -X GET "https://zerq.yourdomain.com/payments/v1/charge" \
  -H "X-Client-ID: <your-client-id>" \
  -H "X-Profile-ID: <your-profile-id>" \
  -H "Authorization: Bearer <your-token>"

You should receive the upstream response. A 401 means credentials are wrong or the profile is expired. A 403 means the client is not authorized for that collection or the IP is restricted.

Step 6 — Verify in Request Logs​

Every gateway request is logged in real time.

  1. Go to Logs → Request Logs.
  2. Find your request (filter by path, method, status code, or client).
  3. Click a log entry to view:
    • Full request and response headers
    • Request/response body (if logging is enabled)
    • Latency, status code, matched proxy, and client identity

The log confirms the request was authenticated, routed, and processed correctly.

Next steps​