/vismanetapi/setting-up-your-integration/developer-portal/interactive-integrations section Creating Interactive Integrations 2025-10-16T11:16:31+02:00 # Interactive Integrations Creating Interactive Integrations ## Interactive Integrations Interactive integrations use the authorization code flow for secure authentication and access to Visma APIs. This flow is adaptable to different application types, each with unique characteristics. ### Application Types #### 1. **Single Page Applications (SPAs)** - **Execution Environment**: Runs entirely in the browser. - **Security Approach**: Implements PKCE to secure authorization as client secrets cannot be safely stored. - **Limitation**: SPAs do not receive refresh tokens because they lack the capability for offline access. #### 2. **Server-Side Web Applications** - **Execution Environment**: Operates on a server, managing secure interactions server-side. - **Security Approach**: Can use traditional `authorization_code` flow with client secrets; PKCE is optional but enhances security. - **Capability**: Eligible for refresh tokens when configured with `offline_access`. #### 3. **Native Applications** - **Execution Environment**: Runs on devices like desktops or mobiles. - **Security Approach**: Uses external browsers for authorization requests; relies on PKCE to protect authorization codes. - **Capability**: Like SPAs, does not typically utilize refresh tokens. ### Authorization Code Flow Steps The authorization code flow involves several key steps, ensuring secure token exchange: #### Step 1: Authorization Request For all interactive applications, initiate the authorization request by generating a `code_verifier` and a `code_challenge` (if PKCE is used). Example Request (Common Structure): ```bash GET https://connect.visma.com/connect/authorize?client_id=YOUR_CLIENT_ID&response_type=code&scope=openid+email+profile&redirect_uri=YOUR_REDIRECT_URI&code_challenge=YOUR_CODE_CHALLENGE&code_challenge_method=S256&state=YOUR_STATE_PARAMETER&ui_locales=YOUR_LOCALE_PREFERENCES ``` Common Parameters: - **client_id**: Unique identifier for your application. - **response_type**: Always `code` for authorization code flow. - **redirect_uri**: Specifies where the response is sent; must match registration details. - **code_challenge (PKCE)**: BASE64-URL-encoded SHA256 hash; optional for server-side apps. - **state**: Prevents CSRF and ensures response integrity. - **ui_locales**: Preferred languages for user interface. #### Step 2: User Consent (Optional) Users may be prompted to approve the application access request. This step depends on application settings and user privileges. #### Step 3: Authentication Response Upon user consent, Visma returns an authorization code to the specified redirect URI. Sample Response: ``` YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE_PARAMETER ``` ### Step 4: Exchange Authorization Code for Tokens Use the received authorization code and the `code_verifier` (for PKCE) to request access tokens. Example Token Request: ```bash curl --request POST --url https://connect.visma.com/connect/token --header 'content-type: application/x-www-form-urlencoded' \ --data 'grant_type=authorization_code&redirect_uri=YOUR_REDIRECT_URI&code=AUTHORIZATION_CODE&client_id=YOUR_CLIENT_ID&code_verifier=YOUR_CODE_VERIFIER&client_secret=YOUR_CLIENT_SECRET' ``` - **grant_type**: `authorization_code` for interactive applications. - **code_verifier**: Necessary for PKCE-enabled flows. - **client_secret**: Required for server-side apps unless PKCE is used. ### Important Notes - **Refresh Tokens**: Only server-side web applications configured with `offline_access` can request refresh tokens to renew expired access tokens. - **Security Best Practices**: Use https and secure state management to prevent CSRF attacks. By effectively implementing this standardized process, developers ensure secure and efficient integration with Visma API resources, tailored to their application type.