Guide

Credentials and tokens

A credential identifies your integration inside one customer's Visena instance; an access token is the short-lived proof you send with every call. This page is the mechanics of both — created in seconds, revocable in one call, and the secret is shown exactly once.

Concepts defines what a credential, a token and a scope are, and where each one lives. This page assumes you have read that and want to make them. It is three jobs that belong together, so it is long on purpose:

• Manage API credentials — the credential API: create, list, revoke, rotate.
• Create a credential and a token in the interface — the same journey click by click, with every screen shown.
• Get an access token — the token request, the scope rules, a cache to copy, and the errors.

Manage API credentials

A credential is a pair: a clientId that names it and a clientSecret that proves it. Everything below happens inside one customer's instance, against that instance's own URL — under /{instanceName}/auth/api/v1/. The credential endpoints carry a {locale} segment after the version — /acme/auth/api/v1/en/credentials — while the token endpoint does not.

Who creates it

Credentials are created inside the customer's instance, authenticated with a Visena user login — so in most integrations, the customer's Visena administrator creates the credential and hands you the pair through a secure channel. The requests below document what happens in that step, whether it is you or the customer performing it.

Create a credential

Two fields, both required:

A credential created through this API always acts as the user who creates it. For one that acts as somebody else, it is created in the interface instead — see on-behalf credentials.

curl -X POST https://api.visena.example/acme/auth/api/v1/en/credentials \
  --cookie "X-ACCESS-TOKEN=<your Visena login session>" \
  -H "Content-Type: application/json" \
  -d '{ "label": "erp-sync-prod", "accessLevel": "READ_WRITE" }'

{
  "id": "aX8k2m",
  "label": "erp-sync-prod",
  "clientId": "acme-partner-3f9a",
  "accessLevel": "READ_WRITE",
  "clientSecret": "vco_9tK2…",
  "createdAt": "2026-08-21T09:14:03.482+02:00"
}

List your credentials

Listing returns metadata only — never a secret. Use it to see what exists and find the id you need for revocation.

curl https://api.visena.example/acme/auth/api/v1/en/credentials \
  --cookie "X-ACCESS-TOKEN=<session>"

# 200 OK
[
  { "id": "aX8k2m", "label": "erp-sync-prod", "clientId": "acme-partner-3f9a",
    "accessLevel": "READ_WRITE", "createdAt": "2026-08-21T09:14:03.482+02:00" }
]

Revoke a credential

Revocation is a DELETE on the credential's id (the masked id from create/list — not the clientId).

curl -X DELETE https://api.visena.example/acme/auth/api/v1/en/credentials/aX8k2m \
  --cookie "X-ACCESS-TOKEN=<session>"

# 204 No Content — done

Rotation, in three moves

1. Create the replacement — same label convention, e.g. erp-sync-prod-2026q4. Both credentials work during the switch; there is no downtime window.
2. Deploy the new pair — update your secret store, roll your services, confirm token minting works with the new clientId.
3. Revoke the old credential — DELETE …/credentials/{id}. Anything still using it fails fast and loudly, which is exactly what you want.

Rotate on a schedule that matches your security policy, and always when a person with access to the secret leaves the project.

On-behalf credentials

When your integration must act as a specific user — say, filing documents in the name of a case worker — ask the customer's administrator for an on-behalf credential for that user. These are issued through Visena's administration tooling, not the self-service API above. They behave identically with two differences:

• Token requests must use the act-as-user: scopes — act-as-user:read act-as-user:write for a credential created as Les og skriv (Read and write), act-as-user:read alone for one created as Bare lesing (Read only). Asking for plain read write returns 400 invalid_scope.
• Every change is recorded with both the subject user and your acting identity, and mutation responses carry an actedBy field naming the actor.

Create a credential and a token in the interface

The same journey, done click by click in the Visena web application: create a credential, exchange it for a token, fetch your first record — with every screen shown. This is the user-interface route, the one a customer's administrator normally takes.

1. Open the API credentials page. In Visena, follow Admin → Tilgangskontroll → Administrer API-tilganger (Access control → Manage API credentials). The page lives at /admin/access-control/api-credentials and lists every credential in the instance.

   

2. Create the credential. Click Ny API-tilgang (New API credential). The dialog asks for three things:

   • Navn (Name) — free text, so you can recognise the credential later. Name it after the system that will hold it: erp-sync-prod beats my-token.
   • Gjelder for (Applies to) — Meg selv (Myself) or På vegne av en annen (On behalf of someone else). Pick the latter and a person picker appears; that person becomes the credential's aktør (actor): the API client does everything as them, with exactly the access they have in origo, while you are recorded as its creator. Step 4 below shows how the choice reads in the overview.
   • Tilgang (Access) — Les og skriv (Read and write) or Bare lesing (Read only). This is the ceiling on everything the credential can ever mint, and it cannot be changed afterwards: choose Bare lesing when the integration is never meant to write, and it cannot obtain a token that does. Two ceilings, not one explains how it relates to the scope you ask for per token.

   Then Opprett (Create).

   

3. Copy the client id and the secret. The credential is created, and Visena shows the two values the OAuth 2.0 flow needs:

   • Klient-ID (Client ID) — identifies the credential. This is your client_id.
   • Klienthemmelighet (Client secret) — a vco_… value that acts as the password. This is your client_secret.
   ✓

   Copy the secret before closing the dialog. Visena stores only a one-way hash, so this is the one moment it exists in readable form. Put it straight into your secret manager. If it is lost there is no reveal and no reset: create a new credential and revoke this one.

   

4. Know who the token acts as. Every credential is tied to a user identity, and calls made with its tokens act as that user, with that user's permissions. The Gjelder for choice from step 2 decides who that is:

   Choice	The token authenticates as
   Meg selv Myself	The person who created the credential. Aktør (Actor) and Opprettet av (Created by) then name the same person — you.
   På vegne av en annen On behalf of someone else	The user you picked. The overview shows them under Aktør (Actor) and you under Opprettet av (Created by). Tokens for these credentials must be requested with the act-as-user:… scopes; see on-behalf credentials.

   The overview lists every credential with its name, client id, Aktør (Actor), Tilgang (Access), status, Sist brukt (Last used) — stamped when a token from the credential is used against the API, not when the token was fetched — and when it was created, and by whom:

   

5. Exchange the credential for a token. POST the pair to the gateway's token endpoint with the standard OAuth 2.0 client_credentials grant. The screenshots below send the credential in the form body, which is what an API client does by default; for production, HTTP Basic is the recommended form — both are covered under the token request.

   Endpoint

   POST {baseUrl}/{instanceName}/auth/api/v1/token
   Content-Type: application/x-www-form-urlencoded

   Field	Value
   grant_type	client_credentials
   scope	What the token may do: read, write or read write. Mandatory — there is no default.
   client_id	The Klient-ID from step 3
   client_secret	The Klienthemmelighet from step 3

   i

   Only reading? Ask for scope=read. Such a token can never mutate anything, no matter what the underlying user is allowed to do — Read-only access shows that guarantee being enforced, with the 403 to prove it.

   Request — curlCopy

   curl -X POST https://api.visena.example/acme/auth/api/v1/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "scope=read" \
     -d "client_id=<your Klient-ID>" \
     -d "client_secret=<your Klienthemmelighet>"

   Response — 200 OKCopy

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

   

   

   The token is opaque, lives for expires_in seconds, and there is no refresh token: when it expires, repeat this request. Cache the token has the pattern, and the error table the full list of token-endpoint failures.

6. Make the first call. Send the token as a Bearer header to the resource server through the same gateway. The path carries the instance name, the API version and the locale — fetching one person, for example:

   Request — curlCopy

   curl "https://api.visena.example/acme/api/v1/en/person/KDiJs47rD4THRo5uPwlESr0" \
     -H "Authorization: Bearer <access_token>"

   

   

That is the whole loop: credential → token → call. From here, Making requests covers URL anatomy, masked ids, locales and the shapes every endpoint returns, and Read-only access covers what scope=read rules out.

Get an access token

One standard OAuth 2.0 request turns your credential into a short-lived bearer token, scoped to exactly what you ask for.

The token request

POST to /{instanceName}/auth/api/v1/token with the client_credentials grant. That is the whole path: the instance name, then the fixed auth/api/v1 auth surface, then token — no locale segment, and nothing between. Authenticate with HTTP Basic (recommended) or with client_id/client_secret form fields — both are standard OAuth 2.0.

curl -X POST https://api.visena.example/acme/auth/api/v1/token \
  -u "acme-partner-3f9a:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=read write"

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

• access_token is opaque — an unreadable string, not a JWT. Never try to decode or inspect it; just send it back as a bearer header.
• expires_in is seconds until expiry. Read it from the response every time — never hardcode a lifetime.
• There is no refresh token. When the token expires, run the same request again.

Setting scopes — the rules

You may request your credential's full scope set or any subset of it:

Ask for read in export jobs and dashboards, and for the write scope only in the jobs that actually change something.

Asking for a scope your credential does not hold — including asking an on-behalf credential for plain read write — returns 400 invalid_scope. The scopes are then enforced per request: GETs need the read scope, all mutations need the write scope. A token minted with read only gets 403 on every POST/PUT/PATCH/DELETE.

Cache the token, don't hammer the endpoint

Mint once, reuse until shortly before expiry, then mint again. A 60-second safety margin absorbs clock skew and in-flight requests:

const baseUrl = "https://api.visena.example";
const instanceName = "acme";

let cachedToken = null;
let cachedTokenExpiresAt = 0;

async function getAccessToken() {
	if (cachedToken && Date.now() < cachedTokenExpiresAt - 60_000) {
		return cachedToken;
	}
	const basicAuth = Buffer
		.from(`${process.env.VISENA_CLIENT_ID}:${process.env.VISENA_CLIENT_SECRET}`)
		.toString("base64");
	const response = await fetch(`${baseUrl}/${instanceName}/auth/api/v1/token`, {
		method: "POST",
		headers: {
			"Authorization": `Basic ${basicAuth}`,
			"Content-Type": "application/x-www-form-urlencoded"
		},
		body: "grant_type=client_credentials&scope=read%20write"
	});
	if (!response.ok) {
		throw new Error(`token request failed: ${response.status}`);
	}
	const token = await response.json();
	cachedToken = token.access_token;
	cachedTokenExpiresAt = Date.now() + token.expires_in * 1000;
	return cachedToken;
}

When the token endpoint says no

Token-endpoint failures use the standard OAuth 2.0 error body — { "error": "…", "error_description": "…" }:

That OAuth error body is the token endpoint's own shape. Everything behind the token — the business API you call with it — answers with RFC 9457 problem documents instead; see Errors and troubleshooting.

Next comes the request itself: URL anatomy, masked ids and the locale segment in Making requests. For what the pieces on this page are rather than how to make them, go back to Concepts.