Quickstart

Before you start

You need two things from your Zivio administrator (or support@zivio.com):

An OAuth client — a client ID and client secret. Tell them which scopes your integration needs.
Your organisation identifier, sent as the zivio-tenant-id header on every request. The regional API endpoints serve every Zivio organisation, so each request has to say which one it is for. See Identifying your organisation.

The client secret is shown once when the client is created. Store it somewhere secure; it cannot be retrieved again.

Exchange your credentials for an access token

Post your credentials to the token endpoint, listing the scopes you want as a space-separated string.

curl -X POST https://api.zivio.net/api/v4/oauth/token \
  -H "zivio-tenant-id: $ZIVIO_TENANT_ID" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id=$ZIVIO_CLIENT_ID \
  -d client_secret=$ZIVIO_CLIENT_SECRET \
  -d scope="welcome:read projects:read"

import os, requests

resp = requests.post(
    "https://api.zivio.net/api/v4/oauth/token",
    headers={"zivio-tenant-id": os.environ["ZIVIO_TENANT_ID"]},
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["ZIVIO_CLIENT_ID"],
        "client_secret": os.environ["ZIVIO_CLIENT_SECRET"],
        "scope": "welcome:read projects:read",
    },
)
token = resp.json()["access_token"]

const resp = await fetch("https://api.zivio.net/api/v4/oauth/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    "zivio-tenant-id": process.env.ZIVIO_TENANT_ID,
  },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.ZIVIO_CLIENT_ID,
    client_secret: process.env.ZIVIO_CLIENT_SECRET,
    scope: "welcome:read projects:read",
  }),
});
const { access_token } = await resp.json();

The response carries the token and its lifetime:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "welcome:read projects:read"
}

A 404 Tenant Unknown here means the zivio-tenant-id header is missing or wrong — it is checked before your credentials are.

Check the scope field in the response. You are granted the intersection of what you asked for and what your client is allowed — asking for more than you hold does not fail, it just returns less.

Confirm the token works

GET /welcome is the whoami endpoint. It tells you which user the token acts as and which scopes were granted, which makes it the right first call in any integration.

curl https://api.zivio.net/api/v4/welcome \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "zivio-tenant-id: $ZIVIO_TENANT_ID"

{
  "message": "Welcome to Zivio",
  "owner": { "id": 12345, "email": "api-user@company.com" },
  "scopes": "welcome:read projects:read"
}

Make a real request

Send the token as a bearer token on every subsequent call.

curl "https://api.zivio.net/api/v4/projects?limit=5&sort[created_at]=desc" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "zivio-tenant-id: $ZIVIO_TENANT_ID"

This needs the projects:read scope. If you left it out of your token request you will get a 403 with error: insufficient_scope naming the scope you need.

Discover what you can filter

Every resource has a /help endpoint listing its filterable attributes, operators and enum values — no guesswork required.

curl https://api.zivio.net/api/v4/projects/help \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "zivio-tenant-id: $ZIVIO_TENANT_ID"

See Filtering and pagination for the query syntax.

Next steps

Scopes

Pick the narrowest set your integration needs.

API Reference

Every endpoint, with a request playground.

Get started

Authentication

Using the API

MCP server

Webhooks

Migration

Before you start

Next steps

Scopes

API Reference

​Before you start

​Next steps

Scopes

API Reference

Before you start

Next steps