/vismanetapi/setting-up-your-integration/authentication section Authentication to Visma Net API via Visma Connect involves multi-tenant identity providers. Requires creating an app in Visma Developer Portal. 2025-10-15T10:34:38+02:00 # Authentication Authentication to Visma Net API via Visma Connect involves multi-tenant identity providers. Requires creating an app in Visma Developer Portal. Authentication to Visma Net API is done through Visma Connect. Visma Connect is a multi-tenant identity provider. Tenants are organizations (businesses) that provide an API-context. A given user may have access to multiple tenants and will choose which to connect to your application upon each single sign-on flow. > [!TIP] > You'll need to create an application in the Visma Developer Portal, available at , before getting started. > [!TIP] > To learn more about this process see this document . Please explore Visma Developer Portal documentation. ## Endpoints Visma Connect endpoint details: | Endpoint | URL | | -------- | --- | | Discovery | | | Authorization | | | Token | | | Userinfo | | | Endsession | | ## Visma Connect Token Your application requests specific permission scopes and is granted an access token upon a user's approval. There are two scenarios that are supported by Visma Connect: - Interactive authentication of users, that must provide their credentials in a login form. That requires the authentication flow to use the *Authorization Code* or *Authorization Code with PKCE* grant type. - Authentication of a service, using a client ID and a client secret. That requires the authentication flow to use the *Client credentials* grant type. Once the authentication process has completed successfully, you can make API calls by providing the valid access token with each API request using the `authorization` header. /vismanetapi/setting-up-your-integration/authentication/oauth page Understanding OAuth2 for Visma API integration, including roles, tokens, scopes, grants, and necessary endpoints for secure resource access. 2025-10-15T10:34:38+02:00 # Understanding OAuth Understanding OAuth2 for Visma API integration, including roles, tokens, scopes, grants, and necessary endpoints for secure resource access. Access to resources and APIs in Visma is done through Visma Connect. This is an identity provider. The OAuth2 flow is used to authorize users and services to access the desired resources. You need to know the basics of OAuth in order to understand the authorization process and build your integration with Visma Net. ## What is OAuth2? OAuth is a standard that allows websites or applications to access, on behalf of an user, resources hosted by other apps (servers). The term OAuth stands for "Open Authorization" and the number 2 refers to the 2.0 version of the standard. The standard allows users to grant client applications consented access to what resources they can access without sharing credentials. OAuth is not intended to authenticate users (that is verifying that a user is who he claims to be) but to authorize them. That means granting access to resources such as remove APIs. > [!NOTE] > > You can read more about OAuth2 here: > > - [OAuth 2.0](https://oauth.net/2/) > - [What is OAuth 2.0?](https://auth0.com/intro-to-iam/what-is-oauth-2/) ## Roles The OAuth standard defines a set of roles that represent components of an authorization system. These roles/components are the following: - **Resource owner**: the system/user that owns a resource and that grants access to that resource. - **Client**: the system that requires access to a protected resource. - **Authorization server**: a server that receives requests from the **Client** for access tokens and issues them after authenticating the **Resource owner** and obtaining consent for the requested access. - **Resource server**: a server that protects the resources and receives access requests to them from the **Client**. The interactions between these components are illustrated in the following image:  ## Access tokens In order to grant access to resources, OAuth2 uses *access tokens*. An access token is basically a document that describes the authorization to access resources on behalf of a user. The OAuth2 standard does not define a format. The JSON Web Token (JWT) is the widely used format. Visma Connect uses the JWT format for access tokens. The JWT token is a base64 encoded document. Typically, you should not be concerned with the content of a token. For debugging purposes, however, you can use the [jwt.io](https://jwt.io) website to inspect the content of a JWT access token. Its payload looks as follows: ### Interactive ```json { "iss": "https://connect.visma.com", "nbf": 1755516249, "iat": 1755516249, "exp": 1755519849, "aud": "https://api.finance.visma.net/erp/interactive", "scope": [ "vismanet_erp_interactive_api:create", "vismanet_erp_interactive_api:delete", "vismanet_erp_interactive_api:read", "vismanet_erp_interactive_api:update" ], "amr": [ "pwd", "remember2sv" ], "client_id": "clientId", "tenant_id": "ddc3c4d6-db00-31ff-2c6a-514268f56b0f", "tenant_external_id": "1234356", "tenant_owner_client_id": "odp", "sub": "ddc3c4d6-db00-31ff-2c6a-514268f56b0f", "auth_time": 1755501468, "idp": "Visma Connect", "llt": 1754980057, "created_at": 1535971848, "acr": "2", "sid": "ddc3c4d6-db00-32ff-2c6a-514268f56b0f" } ``` ### Service ```json { "iss": "https://connect.visma.com", "nbf": 1755506773, "iat": 1755506773, "exp": 1755510373, "aud": "https://api.finance.visma.net/erp/service", "scope": [ "vismanet_erp_service_api:create", "vismanet_erp_service_api:delete", "vismanet_erp_service_api:read", "vismanet_erp_service_api:update" ], "client_id": "clientId", "tenant_id": "ddc3c4d6-db00-31ff-2c6a-514268f56b0f", "tenant_external_id": "1234356", "tenant_owner_client_id": "odp" } ``` An access token contains information such as: - issuer (`iss`) - the destination of the token (`aud`) - issued time (`iat`) - not valid before(`nbf`) - expiration time (`exp`) - subject - whom the token refers to (`sub`) - scopes - list of granted scopes (`scope`) The one what you need to know about are the scopes. >[!NOTE] > > You can read more about access tokens here: > > - [OpenID Connect specifications](https://openid.net/specs/openid-connect-core-1_0.html) > - [Introduction to JSON Web Tokens](https://jwt.io/introduction) ## ID token vs Access token vs Refresh token When you read about OAuth tokens, there are three terms that come up and can be confusing: - **ID token**: this is a document that proves that a user has been authenticated and can carry information about the user. The ID token was introduced by OpenID Connect (OIDC) which is an open standard for authentication used by many identity providers, including Google, Facebook, and Apple. - **Access token**: this is a document that carries information about the authorization to a resource. - **Refresh token**: this is a special kind of token that is used to obtain additional access tokens. An ID or access token is valid for a specific period of time (like 30 seconds or 60 minutes for instance). A refresh token is used to retrieve new access tokens without the need to re-authenticate the user. A refresh token is requested alongside the initial request for an ID and access token and must be stored (securely) by the application. >[!NOTE] > > You can read more about these kinds of tokens here: > > - [ID Tokens vs Access Tokens](https://oauth.net/id-tokens-vs-access-tokens/) > - [ID Token and Access Token: What's the Difference?](https://auth0.com/blog/id-token-access-token-what-is-the-difference/) > - [What Are Refresh Tokens and How to Use Them Securely](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/) ## Scopes Scopes are reasons for which access to a resource is requested. For instance, there can be a scope for reading data, one for inserting and updating, one for deleting. Scopes depend on the resource server. Visma Net defines four scopes per integration type: | Interactive | Service | | ----------- | ------- | | vismanet_erp_interactive_api:create | vismanet_erp_service_api:create | | vismanet_erp_interactive_api:delete | vismanet_erp_service_api:delete | | vismanet_erp_interactive_api:read | vismanet_erp_service_api:read | | vismanet_erp_interactive_api:update | vismanet_erp_service_api:update | >[!TIP] > However, in case of a web application, when you register it with Visma Developer Portal, you need to set the following scopes: `email`, `openid`, and `profile`. Upon reqesting an access token, you need to specify the following scopes: `business-graphql-api:access-group-based` `openid` `email`. These extra scopes are not necessary for services. > > Read more about this here: > > [Web applications registration](./web/setup_web.md) and [GraphQL API Integration](./web/integrations_web.md). > > [Services registration](/businessnxtapi/authentication/service/application_registration/) and [GraphQL API Integration](./service/integrations_service.md). ## Grants Grants are steps a client performs to get authorization for accessing a resource. The authorization framework defines several grant types for different scenarios: - Authorization Code - Implicit - Authorization Code with Proof Key for Code Exchange (PKCE) - Resource Owner Credentials - Client Credentials - Device Authorization Flow - Refresh Token Grant One of the grant types used for Visma Net is **Authorization Code with PKCE**. This flow consists of the following steps: 1. The user clicks a login button/link in the application. 2. The application creates a random `code_verifier` and from it generates a `code_challenge`. 3. The application makes an authorization request to the `/authorize` endpoint of the authorization server with the generated `code_challenge`. 4. The authorization server redirects the user to the login and authorization page. 5. The user authenticates (using a selected option) and may be displayed a consent page that lists the permissions the application is requesting. 6. The authorization server stores the `code_challenge` and redirects the user back to the application, providing a one-time-use `authorization_code`. 7. The application sends the `code_verifier` and the `authorization_code` to the `/token` endpoint of the authorization server. 8. The authorization server verifies the `code_challenge` and the `code_verifier`. 9. The authorization server returns an *ID token*, an *access token*, and optionally, a *refresh token*. 10. The application uses the access token to call an API. 11. The API responds with the requested data.  >[!NOTE] > > You can read more about grants here: > > - [Authentication and Authorization Flows](https://auth0.com/docs/get-started/authentication-and-authorization-flow) > - [OAuth Grant Types: Explained](https://frontegg.com/blog/oauth-grant-types) > - [OpenID Connect & OAuth 2.0 API](https://developer.okta.com/docs/reference/api/oidc/) ## Endpoints and redirect URLs Endpoints and a redirect URL are key parts of the OAuth flow. An authorization server exposes several endpoints that are used at various steps in the authorization flows: | Endpoint | Description | | -------- | ----------- | | `/authorize` | Interact with the resource owner and obtain an authorization grant. | | `/token` | Obtain an access token and/or an ID token by providing an authorization grant or refresh token. | | `/endsession` | End the session associated with the given ID token. | | `/userinfo` | Return claims about the authenticated end user. | >[!TIP] > > To get the URLs of the Visma Connect endpoints check [this page](/businessnxtapi/authentication/). A *redirect URL* is a URL to which the authorization server will redirect the user after the user successfully authorizes an application. A redirect URL contains sensitive information. The authorization server must not redirect the user to arbitrary (unsecure) locations. In order to ensure the user is redirected to an appropriate location, the developers of the application are required to register one or more redirect URL when they create the application. >[!TIP] > > Visma Developer Portal requires you to provide a redirect URL when you register your application in the system. You can read more about that here: [Web Application registration](/businessnxtapi/authentication/web/).