Access Grant Flow

The Access Grant Flow is a process by which an application is granted permission to access a company's data on the T-Gate platform. This flow starts when a company decides to install an application and ends with the application acquiring an access token to access the company's data.

Flow Overview

Application Setup

In order for an application to be on the marketplace, It needs first to setup 4 main attributes, these attributes can be set from your application account → Oauth Management

• form_uri: The form_uri is a critical component of the access grant flow, designed to facilitate direct interaction between a company and an application. Once a company chooses to install an application through the T-Gate marketplace, they are redirected to the application's form_uri. This step takes T-Gate out of the equation, allowing for seamless communication between the company and the application.

👍

Purpose

The form_uri enables company users to be navigated directly to the application, where they can complete any necessary agreements or provide additional information required by the application. This ensures that both parties can finalize their arrangements without further involvement from T-Gate.

🚧

Partner Responsibility

It is your responsibility as a partner application to handle the form_uri page. The form_uri will navigate the company user to a page in your app where they can complete the deal with you. Ensure that this page provides all the necessary information and tools for a smooth and successful onboarding experience.

• redirect_uri: T-Gate uses the OAuth2 flow to grant partner applications access to a company's data. This process requires the application to set up a redirect_uri.

👍

Purpose

a redirect_uri is where T-Gate will redirect the company user after they authorize access to their data. The partner application must implement this URL to correctly receive the authorization code from T-Gate.

🚧

Partner Responsibility

It is your responsibility as a partner application to handle capturing the authorization code sent via the redirect_uri and use it to generate an access token. This token will allow the your application to interact with the company's data.

• client_id & client_secret: After setting up the form_uri and redirect_uri, the application can proceed to generate its client_id and client_secret.
  Together, the client_id and client_secret serve as the credentials that authenticate your application during the OAuth2 flow. The client_id acts as a public identifier, while the client_secret is a confidential key that should be securely stored, as it is only displayed once and if lost, it cannot be recovered and you will have to regenerate a new one.

🔐

Security Reminder

Always keep your client_secret safe and private to ensure your application's integrity and security.

Company Contacts Application

Once a company selects an application to install and chooses the scopes to provide, it is redirected to the application's form_uri. This redirection allows the company to initiate direct communication with the application to finalize any agreements or setups needed.

Authorization Request

After any required agreements are completed, the application needs to guide the company back to T-Gate to authorize the application.

• The application must send the company back to T-Gate at the URL: https://company.t-gate.net/oauth, attaching its client_id and redirect_uri to the URL.

🌐

OAUTH2 URL

A valid URL would look like this <company_portal_url>/oauth?client_id=<your_client_id>&redirect_uri=<your_redirect_uri>.

Example: https://company.t-gate.net/oauth/client_id=xz0c8UGGMlXG21WutLQ6r0ZpeIOSovAZugV29E545cc&redirect_uri=www.your_application_redirect_uri.com

🚧

Company Portal URL

You need to choose the correct company portal URL regarding the environment you are in.
Sandbox URL: https://company-sandbox.t-gate.net Production URL: https://company.t-gate.net

↪️

Redirecting The Company User

Navigating the company user back to T-Gate can be done either by sending him an email, making him press a button or any other mean of your choice

OAUTH2 Flow

T-Gate processes the OAUTH2 flow, during which the company authorizes the application to access its data.

Upon successful authorization, T-Gate redirects the company user back to the application's redirect_uri with an authorization code.

📘

T-Gate Redirection

After a successful authorization, T-Gate will redirect the company_user back to your redirect_uri with a code attached to it as a query parameter

Example: "https://your_application_redirect_uri.com/?code=LHwmrkFH3g4DkI4WxSbAogbhodnxtGjhUoUB5Brgx-Y"

Access Token Acquisition

Handling the Code: The application must handle saving this code and use it to acquire an access token, which is necessary for accessing the company's data.

To exchange your code with an access token and a refresh token, please refer to API Documentation -> Get Access Token

🚧

The authorization code expires after 10 minutes

It is crucial for the application to act promptly to exchange the code for an access token.

Summary

1. Configure Application Endpoints:
   • Ensure form_uri and redirect_uri are correctly set up in the application's configuration alongside your client_id and client_secret .
2. Guide Companies Through the Flow:
   • Provide clear instructions or automated emails to guide companies from selecting your application to completing the authorization.
3. Handle Authorization Codes:
   • Implement logic to securely save and exchange authorization codes for access tokens using the OAUTH2 protocol.
4. Ensure Timely Processing:
   • Since the authorization code expires in 10 minutes, ensure your application processes it promptly to obtain the access token.

By following these steps and implementing the necessary endpoints and logic, your application will be equipped to manage the Access Grant Flow and successfully acquire the permissions needed to access company data on the T-Gate platform.