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):

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.

(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:

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.

Interactive Integrations