/businessnxtapi/authentication/service section Guide for integrating services with Business NXT via GraphQL, including registration, authentication, and setup instructions on Visma Developer Portal. 2024-09-24T15:57:29+02:00 # Services Guide for integrating services with Business NXT via GraphQL, including registration, authentication, and setup instructions on Visma Developer Portal. In order to integrate with Business NXT you must register an application in the Visma Developer Portal and add an integration to Business NXT GraphQL. Here, you will learn how to do this. Services are application do not require user interaction. They enable a machine-to-machine integration. If you do not require user interaction, this is the type of application you should use. To integrate your service with Business NXT using GraphQL, you must do the following: 1. Register your service with the Visma Developer Portal. 2. Register an integration with the Business NXT GraphQL API. 3. Register a user to impersonate your service in Business NXT. 4. Perform authentication with the *client credentials* grant type. 5. Use the URL for queries. In this section, we discuss each of these points. >[!TIP] > > If you are not familiar with the OAuth authorization flows, we recommend that you first read carefully the page [Understanding OAuth](../oauth.md) to familiarize yourself with concepts such as authentication and authorization, access tokens, scopes, grants, endpoints and redirect URLs. You need to have a basic understanding of these concepts in order to properly register your application and setup an integration with Business NXT GraphQL Service API. /businessnxtapi/authentication/service/application_registration page Guidance on registering a service application in the Visma Developer Portal, covering steps, approval, credentials, and local development setup. 2024-09-24T15:57:29+02:00 # Application registration Guidance on registering a service application in the Visma Developer Portal, covering steps, approval, credentials, and local development setup. Registering a service application in the Visma Developer Portal is very similar to registering a web application, although some options are different. You must follow these steps: 1. Logon to [Visma Developer Portal](https://oauth.developers.visma.com). 2. From the menu, select My **Applications** and then press the **Add applications** button.  3. Select the **Service** application type.  4. Fill in the registration form. You must select an application name, a unique client identifier, and a description of your application. When completed, you must press the **Save as draft** button and then **Send for approval**.  5. Your application must be approve by Visma before you can start using it. Before approval, it will display the *Pending approval* status. > [!WARNING] > > Because the **client ID** needs to be stored in the **User** table (see [User setup](vbnxt_service.md) page) and there is a limitation of 24 characters for names in this table, please make sure the value for the **client ID** does not exceed this limit. After the approval process complete, you can add integrations to your application. See [GraphQL API integration](integrations_service.md) to learn how to do that. ## Application Credentials In order to perform the authentication flow using the client credentials grant type, you must have both a *client identifier* and a *client secret*. Client secrets can be generated (and deleted) from the **Credentials** tab in Visma Developer Portal.  > [!NOTE] > > A secret is only visible when it is generated after which you can no longer read it. You must copy and preserve it in a secure place. ## Local App Development For the development of your application on local machines, you must register a local URL for login and redirect. The use of `localhost` is not supported in the Visma Developer Portal but `app.local` can be used instead. Assuming your application runs locally on the 12345 port, use the following configuration: ``` Initiate Login URI: https://app.local:12345/ Frontchannel Logout URI: https://app.local:12345/logout Redirect URIs: https://app.local:12345/signin-oidc ``` /businessnxtapi/authentication/service/integrations_service page Guide for integrating Visma's Business NXT GraphQL API, including selecting APIs, confirming integrations, and initiating OAuth flow post-approval. 2024-09-24T15:57:29+02:00 # GraphQL API integration Guide for integrating Visma's Business NXT GraphQL API, including selecting APIs, confirming integrations, and initiating OAuth flow post-approval. After the approval of the registration of your service application, you can add integrations to Visma APIs. To integrate with Business NXT GraphQL API do the following: 1. Select your application from the **My Applications** main tab and go to **Integrations**. 2. Press the **New integration** button. 3. Search and select the **Business NXT GraphQL Service API** in the combo with available APIs and press **Continue**.  4. Select the `business-graphql-service-api:access-group-based` and press **Continue**.  5. Review the selection and confirm the integration by pressing the **Confirm Integration** button.  6. Wait for the integration to be approved by Visma. Once approved, the integrations become active.  Once your application is integrated with **Business NXT GraphQL Service API**, you can initiate the OAuth flow and create tokens. However, access to a company requires additional steps that must be performed in the Business NXT application. This is described next. /businessnxtapi/authentication/service/user_setup page API documentation for setting up a new user in Business NXT, including creating layouts and assigning application access roles. 2024-09-24T15:57:29+02:00 # User Setup API documentation for setting up a new user in Business NXT, including creating layouts and assigning application access roles. In order to perform operations in company in Business NXT using GraphQL from a service (using an access token with *client credentials* grant type), you must perform in Business NXT the registration steps described below. > [!TIP] > > In order to be able to add users to the `User` table, your Visma.net user must have the `Application access` and `System supervisor` roles assign in `Visma.net Admin`. > >  The setup consists of the following steps: 1. Create a new layout and add the **User** table.  2. Unhide the **Connect Application** column from this table.  3. Add a new user having the same name as the client identifier (*client_id*) of your newly registered service. You must check the *Connect application* checkbox before saving the new user.  4. Either create a new layout or use the same layout and add the **Connect Application Access** table.  5. Add the newly created user to this table. Select the company to which you want to grant access to your service by entering its number in the **Column no.** field.  6. Select the desired access group that defines the access rights for this company.  7. Save the changes to the table. You must repeat the steps 5 and 6 for each company to which you want to grant access for your service. /businessnxtapi/authentication/service/examples section Here you can find some examples for how to set up authorization. 2024-09-24T15:57:29+02:00 # Examples for setting up authorization Here you can find some examples for how to set up authorization. Click the links below to look at examples for how to set up authorization for either Postman or Insomnia. /businessnxtapi/authentication/service/examples/postman page Set up OAuth2.0 with Client Credentials grant type in Postman for authenticating your service via Visma Connect. 2024-09-24T15:57:29+02:00 # Postman Set up OAuth2.0 with Client Credentials grant type in Postman for authenticating your service via Visma Connect. In Postman, you can set the authorization method and details either per request or collection. To authenticate your service, perform the following setup: 1. Choose the **OAuth2.0** authorization type. 2. Select the **Client credentials** grant type. 3. Use the following access token URL: . 4. Fill in the client ID and the client secret. 5. Enter the scope `business-graphql-service-api:access-group-based`. 6. Select **Send as Basic Auth header** option for *Client Authentication*. These settings are shown in the following image:  > [!TIP] > > You can learn more about about authentication in Postman from its official documentation. See [Authorizing requests](https://learning.postman.com/docs/sending-requests/authorization/). /businessnxtapi/authentication/service/examples/insomnia page Guide to setting up OAuth2 Client Credentials in Insomnia for authenticating your service. 2024-09-24T15:57:29+02:00 # Insomnia Guide to setting up OAuth2 Client Credentials in Insomnia for authenticating your service. In Insomnia, you can set the authorization method and details per request. To authenticate your service, perform the following setup: 1. Choose the **OAuth2** authorization type. 2. Select the **Client Credentials** grant type. 3. Use the following access token URL: . 4. Fill in the client ID and the client secret. 5. Enter the scope `business-graphql-service-api:access-group-based`. 6. Select **As Basic Auth Header** option for *Credentials* combo. These settings are shown in the following image:  > [!TIP] > > You can read more about authentication in Insomnia [here](https://docs.insomnia.rest/insomnia/authentication).