Authentication

Integration Toolkit > Authentication

Oneflow Public API uses an API token-based authentication. This token is generated when your end users enable your integration extension in their Oneflow account. You should include the user’s Oneflow token in the request headers when you send the contract request through Oneflow’s Public API. Sending the Oneflow token gives you access to the Oneflow account associated with the token. This token must be saved in your external system to enable integration with Oneflow.

There are two methods to get your users’ Oneflow Extension token and other data when they enable the Oneflow Integration Extension:

Once you choose the authentication method that best suits your needs, Oneflow can assist in creating an extension tailored to your specific integration requirements.

Show Token Authentication

The Show Token Authentication method generates and displays the Extension token within the Oneflow interface once an integration extension is enabled by your end users. Your end users need to copy the token and input in your system configurations manually.

Once the extension is enabled, the Extension token will be in the popup.

As Oneflow Integration developers, you should provide a mechanism to accept the Oneflow token through the system’s frontend, while the backend should allow it to be saved. If additional account-related information is required during the saving process, you can call Oneflow public API Get account-related information endpoint to retrieve and store the account information along with the token.

For that, you have to configure the backend to save the Extension token. Below is the sample pseudocode.

FUNCTION SaveToken
    INPUT: oneflow_token

    BEGIN
        # Step 1: Ensure the API token is present
        IF api_token IS NULL THEN
            RETURN "ERROR: API token is missing"
        END IF

        # Step 2: Get oneflow account information
        oneflow_account_information = Get oneflow account related information by calling GetOneflowAccountInfo with oneflow_token

        # Step 3: Validate retrieved account information
        IF oneflow_account_information IS NULL THEN
            RETURN "ERROR: Failed to retrieve Oneflow account information"
        END IF
        
        # Step 4: Save Oneflow account details and token
        TRY
            oneflow_account_id = Get from oneflow account information
            authentication_details <- {
                oneflow_account_id: oneflow_account_information.id,
                api_token: oneflow_token
            }

            # Simulate saving authentication details to the database
            database <- GET database_instance 
            database.SAVE(authentication_details)
        CATCH exception
            Handle exception
    END

FUNCTION GetOneflowAccountInfo
    INPUT: api_token
    OUTPUT: oneflow account information

    BEGIN
        # Step 1: Attempt to retrieve the user account information
        TRY
	    API_ENDPOINT = 'https://api.oneflow.com/v1/accounts/me'

	    # Set up the headers for the API request
	    DEFINE HEADERS
	        SET "x-oneflow-api-token" IN HEADERS TO api_token
		
	   # Send an HTTP GET request to the API endpoint
	   response = Send GET Request to API_ENDPOINT using HEADERS with SSL Verification Enabled

           # Check the response status code
	   IF response.StatusCode EQUALS 200 THEN
	       RETURN response
        CATCH exception
            Handle the exception
    END

Automatic Authentication

The Automatic Authentication method enables the extension to integrate with the external system automatically upon activation. When users enable the extension, now token will not display to the users, but Oneflow will send a request to the defined endpoint (Setup URL) in your system’s Oneflow Integration along with Oneflow API token and other account information of the end user.

As the Oneflow integration developers, you must provide an endpoint called Setup URL within Oneflow Integration in your system. Oneflow will send the Oneflow Extension Token along with other account information to the provided endpoint when your end users enable or disable the extension.

📘
Note:
Setup URL endpoint should be a post endpoint. Setup URL receives the account ID, event(enable/disable), and extension token in the body.

When you enable the extension, the endpoint will receive the token, and when you disable the extension, the token will be none. To differentiate between requests, you can use event attribute to distinguish whether it’s an enable or disable request.

Below is the sample pseudo code for Setup URL endpoint in your Oneflow Integration.

FUNCTION OneflowConnectionSetupURL
    INPUT: request_body (account_id, event, data { token, email:None })
    OUTPUT: oauth_link OR error message

    BEGIN
        # Step 1: Extract and validate inputs from the request body
        oneflow_token <- GET "data.token" FROM request_body

        IF oneflow_token IS NULL OR oneflow_email IS NULL THEN
            RETURN "ERROR: Missing required headers"
        END IF

        # Step 2: Fetch Oneflow account information
        TRY
            oneflow_account_information <- Get oneflow account related information by calling GetOneflowAccountInfo with oneflow_token
        CATCH UnauthorizedAccessException
            RETURN "ERROR: Invalid Oneflow API Token"
        END TRY

        # Step 3: Retrieve or create authentication record
        oneflow_account_id <- oneflow_account_info.id
        authentication_record <- QUERY Database WHERE oneflow_account_id = oneflow_account_id

        IF authentication_record EXISTS THEN
            # Update existing record
            authentication_record.api_token <- oneflow_token
            UPDATE Database WITH authentication_record
        ELSE
            # Create new record
            authentication_record <- {
                oneflow_account_id: oneflow_account_id,
                api_token: oneflow_token
            }
            INSERT INTO Database VALUES authentication_record
        END IF
    END

Show Token Authentication

Automatic Authentication

📘Note:

📘
Note: