Viskan API documentation

Appearance

Authentication ​

The Viskan API uses the standardized OAuth 2.0 protocol to authorize clients. Viskan issues and validates the access tokens itself — you create an API client directly in Viskan Backoffice and authenticate with the client_credentials grant against Viskan's own token endpoint.

Migrating from Visma Connect? Authentication through Visma Connect still works and is described under Legacy: Visma Connect below. New integrations should use the Viskan Backoffice flow described here.

Rolling out. The Viskan Backoffice flow is being rolled out per environment. Always take the exact token and JWKS endpoints from the OpenID discovery document for the environment you are using rather than hard-coding them, as the host may change during the rollout.

Example ​

Authentication request ​

http
POST /auth/oauth2/token

Host: api.v2.viskan.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=client_credentials
scope=country:read

The client is bound to a tenant when it is created in Backoffice, so the issued token is already scoped to that tenant — there is no tenant_id parameter.

Authentication response ​

json
{
  "access_token": "eyJhb...XGw",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "country:read"
}

Note. Treat the access token as opaque. If you do decode one issued in the development environment, its aud claim names the staging API — dev shares the staging audience.

Calling Viskan API ​

When you've received your access_token as per the example above, you can use this token in your requests to Viskan API, using the Authorization header, like this:

http
Authorization: Bearer <access_token>

Scopes ​

Scopes use the unprefixed format, e.g. country:read, order:create. Each API method lists the scope it requires in the API reference. You grant a client its scopes when you create it in Backoffice.

Discovery ​

Viskan publishes a standard OpenID Provider metadata document at the API root, so OAuth libraries can configure themselves automatically:

text
https://api.v2.viskan.com/.well-known/openid-configuration

It advertises the token endpoint (/auth/oauth2/token) and the JWKS endpoint used to validate the tokens Viskan issues.

How do I get client credentials? ​

You create an API client directly in Viskan Backoffice. See "Create an API client in Viskan Backoffice".

Legacy: Visma Connect ​

Historically, Viskan used Visma Connect as its authorization platform. Clients registered in the Visma Developer Portal continue to work, but Visma Connect is being phased out — prefer the Viskan Backoffice flow above for new integrations.

Visma Connect tokens are requested from Visma's token endpoint and carry the legacy viskan:-prefixed scopes:

http
POST /connect/token

Host: connect.visma.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
scope=viskan:country:read
client_id=isv_my-application
client_secret=yj2...7Qp
tenant_id=db100d69-1081-465e-8fbd-ab3d6b94ba0a

Getting Visma Connect credentials and access to a tenant is handled through the Visma Developer Portal and Visma App Store — see the Legacy: Visma Connect onboarding guide.

Client certificates ​

The oldest integrations authenticate with a client certificate rather than OAuth. This mechanism is deprecated and closed to new integrations; existing certificate-based clients should migrate to a Viskan Backoffice API client.

Migrating to the Viskan Backoffice flow ​

  1. Create an API client in Viskan Backoffice and grant it the scopes your integration needs — the unprefixed equivalents of the viskan:-prefixed scopes you use today (viskan:country:read becomes country:read). If your integration uses viskan-global:-prefixed scopes, contact Viskan — global scopes cannot be granted to Backoffice-created API clients.
  2. Switch your token requests from Visma's connect.visma.com/connect/token to Viskan's api.v2.viskan.com/auth/oauth2/token, using the new client's id and secret. Drop the tenant_id parameter — the client is already bound to its tenant.
  3. Point token validation at Viskan's discovery document (above) instead of Visma Connect's.
  4. Once every integration is migrated, retire the Visma Connect application.