Skip to main content

Publish Your First API

This guide walks through publishing an API on Zerq end-to-end — from creating a collection to verifying a live authenticated request in the logs. Estimated time: 15 minutes.

Step 1 — Create a Collection​

A Collection groups one or more API endpoints that share a base path and target upstream.

  1. In the Management UI sidebar, click Collections.
  2. Click New Collection.
  3. Fill in the required fields:
    • Name — a clear, descriptive label (e.g. Payments API)
    • Base Path — the URL prefix for all routes in this collection (e.g. /payments)
    • Target Base URL — the upstream service URL (e.g. https://api.payments.internal)
    • Description (optional) — shown in the Developer Portal
  4. Click Save. The collection is created in Draft status.
tip

The collection base path must be unique across your Zerq deployment. Choose a path that reflects the API's domain.

Step 2 — Add a Proxy Route​

A Proxy maps one inbound request pattern to one upstream endpoint.

  1. Open the collection you just created.
  2. Click Add Proxy.
  3. The setup wizard opens. Work through each step:

Step 1 — Info

  • Enter a Name (e.g. List Charges) and optional Description.
  • The description appears in the Developer Portal for consumers.

Step 2 — Route

  • Set the HTTP Method (e.g. GET).
  • Set the Path — this is appended to the collection base path. For example, /v1/charges becomes /payments/v1/charges.
  • Set the Target Path — the path on the upstream (e.g. /charges).

Step 3 — Headers

  • Add any headers to inject or forward upstream. Each header can be:
    • Static — a literal value (shown with a purple badge)
    • Env Var — resolved from a container environment variable at runtime (shown with a blue badge)

Step 4 — Parameters

  • Define path parameters (e.g. {chargeId}), query parameters (e.g. limit, cursor), and their types.
  • Parameters with an enum constraint will render as dropdowns in the Developer Portal testing console.

Step 5 — Schema

  • Add JSON Schema (draft-07) for the request body and response body.
  • Schemas populate the OpenAPI export and the portal documentation automatically.

Step 6 — Review

  • Confirm all settings and click Save. The proxy is saved in Draft status.
  1. Publish the proxy: click Publish on the proxy row (or use Publish All on the collection).

Step 3 — Create a Client​

A Client represents the application or team that will consume this API.

  1. Go to Access Control → Clients.
  2. Click New Client.
  3. Fill in:
    • Name — identifies the application (e.g. Mobile App)
    • Email — primary contact email for this client
  4. Assign the client to your collection by clicking Add Collection and selecting it.
  5. Click Save.

Step 4 — Create a Profile and Set Auth​

A Profile holds the authentication credentials for a client.

  1. Open the client you just created.

  2. Click Add Profile.

  3. Enter a Profile Name (e.g. Production).

  4. Choose an Auth Type:

    TypeWhen to use
    tokenServer-to-server; Zerq issues a bearer token
    jwtShort-lived HMAC-signed JWT; client generates each request
    oidcToken issued by your identity provider
    mtlsCertificate-based mutual authentication
    noneOpen/internal endpoints with no auth

  5. Click Save. The profile credentials are shown once — copy the token now.

The profile page shows the token's expiry state:

  • Valid (green) — active and usable
  • Expiring Soon (amber) — expires within 24 hours, rotate soon
  • Expired (red) — rotate immediately

Step 5 — Publish the Collection​

Return to the collection detail page and click Publish. This makes the collection and all published proxies live on the gateway.

note

Proxies must also be individually published. Use the Publish All button to publish everything in the collection at once.

Step 6 — Make a Test API Call​

With your credentials and the collection live, send a real request through the gateway:

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

Replace the header values with the values from the profile detail page. A successful response returns the upstream API's data.

Common errors:

  • 401 — token missing, expired, or wrong header format
  • 403 — client not assigned to the collection, or profile inactive
  • 404 — proxy not found or not published

Step 7 — Verify in Request Logs​

Every gateway request is logged.

  1. Go to Logs → Request Logs.
  2. Find your request — filter by path /payments/v1/charges or by client ID.
  3. Click the log entry to view:
    • Request and response headers
    • Status code, latency, upstream response time
    • Which client and profile made the request
    • Any error details

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

Next steps​