🔑️ What an UI Token is
A UI token is a token that's used to authenticate a user in the fetchdocs UI. It's directly connected to an identity. A frontend user needs to authenticate to access and use the fetchdocs UI. Tasks like creating, updating, and deleting connections, via the frontend UI, are only possible with a valid UI token.
For security reasons, the UI token is only valid for a limited time. After the token expires, the client needs to request a new token for the identity. The token is valid for 30 minutes. That's short enough to prevent misuse, but long enough to allow the user to perform tasks in the UI.
💎 How to create a UI Token
To create a UI token, you need to send a POST request to the POST /token endpoint. The request must include the identity_uuid.
You may also want to provide additional information, that controls the behavior of the frontend UI.
The following parameters are available:
| Parameter | Required? | Type | Description |
|---|---|---|---|
identity_uuid |
required | string | The UUID of the identity the token belongs to. |
return_url |
required | string | The URL to which fetchdocs redirects the user after login. fetchdocs adds some additional parameters and signs the URL to avoid manipulation. |
integration_id |
optional | string | Preselect the integration by providing an integration_id. The UI renders directly in the add view and the user isn't able to select a different integration. |
connection_uuid |
optional | string | Preselect the connection by providing its UUID. The UI renders directly in the edit view and the user isn't able to select a different connection or integration. |
The response contains the UI token, the expiration date, a one-time handoff_code and a ready-made handoff_url. The token is a JWT token that's signed by fetchdocs and is valid for 30 minutes.
After fetching the token, redirect the user to the frontend UI. There are two ways to do that:
Option 1: with the handoff code (recommended)
Redirect the user to the handoff_url from the response:
The frontend exchanges the code for the token right after loading, so the token itself never appears in a URL and can't leak through browser history, proxy or server logs or Referer headers. A code can only be used once and expires after 2 minutes, so create the token right before you redirect the user.
Option 2: with the token
Include the token as the query parameter token:
The token stays valid for 30 minutes wherever the URL ends up, which is why we recommend option 1.
📘 API reference
For more information about the API endpoint
POST /token, please refer to the API reference.