Guide

Getting started

Three moves take you from nothing to a real record in your own terminal: get a credential, exchange it for an access token, call the API. This page ends with you having made that call.

Everything is plain HTTPS and JSON over standard OAuth 2.0, so any language with an HTTP client works — and the examples below need nothing but curl and a shell. Read this page once end to end and you will have the shape of every request you ever send to the Partner API; the guides after it fill in the details.

The whole flow in three moves

There is no handshake to negotiate, no SDK to install and no session to keep alive. A credential identifies your integration, a token proves it for a while, and the token authorises each call. The three moves differ mainly in how long what they give you lasts, which is what decides where you keep it.

1. Get a credential. A clientId and secret pair, created inside the customer's Visena instance by an administrator there. It identifies your integration and decides which user its calls act as — see Credentials and tokens.
2. Exchange it for an access token. One standard OAuth 2.0 client_credentials request against /{instanceName}/auth/api/v1/token returns a short-lived bearer token with exactly the scopes you asked for. There is no refresh token: when it expires, ask again.
3. Call the API. Send the token as Authorization: Bearer on every request. Create, read, update, delete, list and sync — the conventions are the same for all nine resources, and Making requests covers them.

What you need before you start

Four values, and you have them all before you write a line of code. Every example on this page uses the placeholders in the right-hand column, so you can substitute yours once and copy the rest verbatim.

The credential itself is created by an administrator in the customer's own instance, under Admin → Tilgangskontroll (access control) → Administrer API-tilganger (manage API credentials). If someone has already handed you a client id and a secret, you have everything this page needs; if not, Credentials and tokens is the page to send them.

A 60-second taste

Four commands in a terminal: set your values, exchange the credential for a token, then read the first page of people in the instance. Nothing is created or changed, and the token asks for read only, so this is safe to run against a live instance.

Set your values

Substitute the three values from the table above. The secret is read from a prompt rather than typed into the command, so it never lands in your shell history.

# The values from the table above — substitute your own.
export VISENA_BASE_URL="https://api.visena.example"
export VISENA_INSTANCE="acme"
export CLIENT_ID="acme-partner-3f9a"

# Prompt for the secret, so it stays out of your shell history.
read -rs -p "Client secret: " CLIENT_SECRET && echo
export CLIENT_SECRET

Get an access token

The token endpoint takes the credential over HTTP Basic — the form that belongs in production — and the standard client_credentials grant. scope is mandatory and has no default: state exactly what the token may do.

curl -sS -X POST "$VISENA_BASE_URL/$VISENA_INSTANCE/auth/api/v1/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=read"

{
  "access_token": "dcrEUVpMEpYqbdsDKawBb1yTqIAELMgqIO4KrN…",
  "scope": "read",
  "token_type": "Bearer",
  "expires_in": 86399
}

The token is opaque — do not parse it — and lives for expires_in seconds. Note that the response echoes the scope it actually granted; that is the value worth asserting in a test. A production integration mints one token, caches it and re-mints shortly before expiry, which Credentials and tokens shows with a cache you can copy.

Make the call

Paste the access_token from the response and send it as a bearer token. The path carries the instance name, the API version and a locale, then the resource — person, singular, like every resource in the API.

# Paste the access_token from the response above.
export ACCESS_TOKEN="dcrEUVpMEpYqbdsDKawBb1yTqIAELMgqIO4KrN…"

# The first page of people in this instance.
curl -sS "$VISENA_BASE_URL/$VISENA_INSTANCE/api/v1/en/person?offset=0&limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "totalItems": 428,
  "totalPages": 22,
  "page": 0,
  "size": 20,
  "items": [
    { "id": "xK9mQ2",
      "firstName": "Kari",
      "lastName": "Nordmann",
      "primaryEmail": "kari.nordmann@example.com",
      "isActive": true },
    …19 more…
  ],
  "links": { "self": "…", "next": "…/person?offset=20&limit=20" }
}

That is the entire model: credential → token → call. The ids are opaque strings like xK9mQ2 — store them exactly as received and echo them back verbatim rather than parsing or constructing them.

If the first call does not work

Failures are machine-readable, and the five below cover almost every first attempt. The token endpoint answers with the standard OAuth 2.0 error body; the API itself answers with an RFC 9457 problem document.

Every other status, the problem-document fields to log, and a retry policy that will not make things worse are in Errors and troubleshooting.

With that call answered, the rest is detail. Three pages, in the order most teams want them:

Walking a whole dataset or syncing only what changed is Lists, paging and sync; every endpoint of every resource is in the API reference; and before you point an integration at production, work through Going live.