HomeAPI Reference
HomeAPI Reference
HomeAPI Reference
API Reference
  1. Synergist REST API v6.0
  2. Overview

Testing the Synergist API with Postman

Testing the Synergist API with Postman

This guide covers importing the example Postman collection and using Postman's built-in
credential handling instead of putting user/password/sha512password in a URL — the pattern
most of the existing API doc examples still show. See
Synergist API Authentication for the full
authentication reference this guide builds on.

Why not query-string credentials?

A GET (or POST) request like:

GET /jsonapi/activities.json?company=1&version=4&user=user&password=user

puts the password in the URL, which typically ends up in:

  • server and reverse-proxy access logs
  • browser history (if ever opened directly in a browser)
  • the Referer header sent to any third-party resource the response page loads

Postman — and every other HTTP client — has dedicated, non-URL ways to send credentials that
avoid all three. Use those instead.

Get the collection + environment

Copy each block below into its own local file (matching the filename shown), then import both
into Postman.

Synergist-API.postman_collection.json:

{
  "info": {
    "name": "Synergist API",
    "description": "Example requests for the Synergist HTTP API (/jsonapi, /xmlapi, /csvapi), covering the three authentication methods documented in the Synergist API Authentication guide.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://<your-server>.synergist.cloud",
      "type": "string"
    },
    { "key": "company", "value": "1", "type": "string" },
    { "key": "version", "value": "6", "type": "string" }
  ],
  "item": [
    {
      "name": "OAuth 2.0 (recommended)",
      "item": [
        {
          "name": "1. Get an access token (Authorization Code + PKCE)",
          "request": {
            "auth": {
              "type": "oauth2",
              "oauth2": [
                {
                  "key": "grant_type",
                  "value": "authorization_code_with_pkce",
                  "type": "string"
                },
                {
                  "key": "authUrl",
                  "value": "{{base_url}}/oauth/authorize",
                  "type": "string"
                },
                {
                  "key": "accessTokenUrl",
                  "value": "{{base_url}}/oauth/token",
                  "type": "string"
                },
                {
                  "key": "clientId",
                  "value": "{{client_id}}",
                  "type": "string"
                },
                {
                  "key": "clientSecret",
                  "value": "{{client_secret}}",
                  "type": "string"
                },
                {
                  "key": "redirectUri",
                  "value": "{{redirect_uri}}",
                  "type": "string"
                },
                {
                  "key": "scope",
                  "value": "openid email profile",
                  "type": "string"
                },
                {
                  "key": "challengeAlgorithm",
                  "value": "S256",
                  "type": "string"
                },
                { "key": "addTokenTo", "value": "header", "type": "string" },
                {
                  "key": "client_authentication",
                  "value": "body",
                  "type": "string"
                }
              ]
            },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/.well-known/openid-configuration/openid_config.json",
              "host": ["{{base_url}}"],
              "path": [
                ".well-known",
                "openid-configuration",
                "openid_config.json"
              ]
            },
            "description": "Use Postman's built-in OAuth 2.0 auth helper (Authorization tab, above) to run the full Authorization Code + PKCE flow and fetch a token — click 'Get New Access Token'. This request itself just hits the discovery document so you can confirm the endpoint URLs first."
          }
        },
        {
          "name": "2. Call the API with a Bearer token",
          "request": {
            "auth": {
              "type": "bearer",
              "bearer": [
                {
                  "key": "token",
                  "value": "{{access_token}}",
                  "type": "string"
                }
              ]
            },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/jsonapi/projects.json?company={{company}}&version={{version}}&action=list",
              "host": ["{{base_url}}"],
              "path": ["jsonapi", "projects.json"],
              "query": [
                { "key": "company", "value": "{{company}}" },
                { "key": "version", "value": "{{version}}" },
                { "key": "action", "value": "list" }
              ]
            },
            "description": "Replace {{access_token}} (collection/environment variable) with a token obtained from request 1, or let Postman inject it automatically once the OAuth2 auth helper above has fetched one."
          }
        },
        {
          "name": "3. Refresh an access token",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"grant_type\": \"refresh_token\",\n  \"client_id\": \"{{client_id}}\",\n  \"client_secret\": \"{{client_secret}}\",\n  \"refresh_token\": \"{{refresh_token}}\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/oauth/token",
              "host": ["{{base_url}}"],
              "path": ["oauth", "token"]
            }
          }
        }
      ]
    },
    {
      "name": "HTTP Basic Auth (legacy fallback)",
      "item": [
        {
          "name": "Create a project (Basic Auth)",
          "request": {
            "auth": {
              "type": "basic",
              "basic": [
                {
                  "key": "username",
                  "value": "{{basic_username}}",
                  "type": "string"
                },
                {
                  "key": "password",
                  "value": "{{basic_password}}",
                  "type": "string"
                }
              ]
            },
            "method": "POST",
            "header": [],
            "body": {
              "mode": "formdata",
              "formdata": [
                { "key": "version", "value": "{{version}}", "type": "text" },
                { "key": "company", "value": "{{company}}", "type": "text" },
                { "key": "action", "value": "create", "type": "text" },
                {
                  "key": "input",
                  "value": "{\"data\":[{\"projectClientCode\":\"1/WORK\",\"projectName\":\"Postman example project\"}]}",
                  "type": "text"
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/jsonapi/projects.json",
              "host": ["{{base_url}}"],
              "path": ["jsonapi", "projects.json"]
            },
            "description": "Uses Postman's native Basic Auth tab (RFC 7617), not a hand-rolled header. IMPORTANT: {{basic_password}} must be the account's PLAINTEXT password, not a pre-hashed sha512password value — confirmed by source reading and a live test (2026-08-19)."
          }
        }
      ]
    }
  ]
}

Synergist-API.postman_environment.json:

{
  "name": "Synergist API - example",
  "values": [
    {
      "key": "base_url",
      "value": "https://<your-server>.synergist.cloud",
      "type": "default",
      "enabled": true
    },
    { "key": "company", "value": "1", "type": "default", "enabled": true },
    { "key": "version", "value": "6", "type": "default", "enabled": true },
    {
      "key": "client_id",
      "value": "<oauth client id>",
      "type": "secret",
      "enabled": true
    },
    {
      "key": "client_secret",
      "value": "<oauth client secret>",
      "type": "secret",
      "enabled": true
    },
    {
      "key": "redirect_uri",
      "value": "https://oauth.pstmn.io/v1/callback",
      "type": "default",
      "enabled": true
    },
    { "key": "access_token", "value": "", "type": "secret", "enabled": true },
    { "key": "refresh_token", "value": "", "type": "secret", "enabled": true },
    {
      "key": "basic_username",
      "value": "<username>",
      "type": "secret",
      "enabled": true
    },
    {
      "key": "basic_password",
      "value": "<plaintext password>",
      "type": "secret",
      "enabled": true
    }
  ],
  "_postman_variable_scope": "environment"
}

In Postman: Import → select both files → pick the "Synergist API - example" environment from
the environment dropdown (top right) → fill in the placeholder values (base_url, client_id,
etc.) for your own account before running anything. version is also an environment variable
(defaults to 6) rather than hardcoded in each request — bump it in one place if you're testing
against a different API version.

OAuth 2.0 (recommended)

The collection's OAuth 2.0 folder uses Postman's native Authorization tab → OAuth 2.0 auth
type, configured for Synergist's Authorization Code + PKCE flow:

  1. Open the "1. Get an access token" request → Authorization tab.
  2. Fill in client_id / client_secret / redirect_uri (an OAuth client must already be
    registered in Synergist — Utilities → OAuth Clients).
  3. Click Get New Access Token. Postman opens a browser window for the login/consent step,
    then captures the resulting access_token/refresh_token for you — no manual curl round-trip.
  4. Save the token to the environment variables (access_token, refresh_token) so the other
    requests in the folder can use it via the Bearer Token auth type.

Tokens expire after 30 minutes; use request 3 ("Refresh an access token") or just click
Get New Access Token again.

HTTP Basic Auth (legacy fallback)

If OAuth 2.0 isn't available yet, use the Authorization tab → Basic Auth type (request in the
"HTTP Basic Auth" folder) rather than hand-building an Authorization: Basic <base64> header or
passing user/sha512password as query params or form fields. Postman handles the
base64-encoding for you.

The Basic Auth password field must be the account's plaintext password (the server hashes it
server-side before comparing) — not the pre-computed sha512password value used elsewhere in the
docs. Confirmed by both source reading and a live test (2026-08-19).

What this doesn't cover

  • The session-token method isn't included here — it's a by-product of an initial Basic Auth /
    username-password login, not something you start a new integration with.
  • Modernized JS/cURL versions of the existing GET-style example calls elsewhere in the docs —
    tracked separately as a larger, not-yet-scoped backlog item.

Updated about 1 hour ago

Updated about 1 hour ago