How to Create a Connection via Link

Overview

The connection via link functionality allows you to:

Generate unique, single-use links for connection creation
Enable clients to authenticate themselves without sharing credentials directly
Automatically create connections in Albato once users complete the authentication flow
Use these connections in solution installations or with the Universal API

Process Flow

The connection creation process involves the following steps:

Create a sharing entity - Generate a one-time token
Form a unique link - Create a shareable URL using the token
User authentication - Client follows the link and provides credentials
Connection creation - Albato automatically creates the connection
Status monitoring - Check sharing status to confirm connection creation
Update sharing (optional) - Regenerate token if needed
Delete sharing (optional) - Revoke token and clean up

Step 1: Create Sharing Entity

Create a new sharing entity to generate a unique token for the connection link.

Endpoint: POST /credentials/grant-access-sharing

Request Body:

{
    "partnerId": 225,
    "title": "Connection by link for CRM Integration"
}

Response:

{
    "success": true,
    "data": {
        "id": 61,
        "partnerId": 225,
        "token": "aZeZWFwAQQ",
        "status": 0,
        "credentialId": null,
        "title": "Connection by link for CRM Integration",
        "dateCreated": null
    }
}

Key Response Fields:

id - Sharing entity identifier (used for status checking)
token - Unique one-time token for the connection link
status - Current status (0 = Waiting)
partnerId - Partner (app) identifier for the connection

Step 2: Form the Unique Link

Create a shareable URL using the id and token from Step 1.

Link Format:

https://connect.integrations-hub.com?id=[id]&token=[token]

Example:

https://connect.integrations-hub.com?id=225&token=aZeZWFwAQQ

Parameters:

id - Partner identifier (from sharing response)
token - Unique one-time token (from sharing response)

Important: The sharing link is valid for 48 hours from creation. After this period, the token expires and cannot be used for connection creation.

Step 3: User Authentication

Share the generated link with your client. When they follow the link, they will:

Land on a dedicated connection page
See a form specific to the integration (partner)
Provide their authentication credentials (API keys, OAuth, etc.)
Complete the connection setup

This step is handled entirely by Albato's interface - no additional API calls are required.

Step 4: Monitor Connection Status

Check the sharing status to confirm when the connection has been successfully created.

Endpoint: GET /credentials/grant-access-sharing/{id}

Example Request:

GET /credentials/grant-access-sharing/61

Status Values:

0 - Waiting (user hasn't completed authentication yet)
1 - Access granted, token invalid (connection successfully created)
2 - Waiting for OAuth (OAuth flow in progress)
3 - Token revoked (sharing cancelled or deleted)

Successful Response (Status = 1):

{
    "success": true,
    "data": {
        "id": 61,
        "partnerId": 225,
        "token": "aZeZWFwAQQ",
        "status": 1,
        "credentialId": 248,
        "title": "Connection by link for CRM Integration",
        "dateCreated": "2025-08-14 19:12:13"
    }
}

Important: When status = 1, the credentialId field contains the unique identifier of the created connection. This ID can be used for solution installations or Universal API operations.

Step 5: Update Sharing Entity (Optional)

If you need to regenerate a sharing token (for example, if the link expired after 48 hours or was compromised), you can update the sharing entity to get a new token.

Endpoint: PUT /credentials/grant-access-sharing/{id}

Use Cases:

Link expired after 48 hours without connection creation
Link was compromised and needs to be regenerated
Need to reset sharing status for reuse

Example Request:

PUT /credentials/grant-access-sharing/72

Response:

{
    "success": true,
    "data": {
        "id": 72,
        "partnerId": 225,
        "token": "ITFxuIUdY2",
        "status": 0,
        "credentialId": null,
        "title": "Connection by link for CRM Integration",
        "dateCreated": "2025-08-15 13:10:24"
    }
}

Important: Updating a sharing entity generates a new token and resets the status to 0 (Waiting). The old token becomes invalid, and you'll need to create a new sharing link with the updated token.

Step 6: Delete Sharing Entity (Optional)

If you no longer need a sharing entity, you can delete it to revoke the token and prevent further use.

Endpoint: DELETE /credentials/grant-access-sharing/{id}

Use Cases:

Cancel sharing when connection is no longer needed
Clean up unused or expired sharing entities
Revoke access for security reasons

Example Request:

DELETE /credentials/grant-access-sharing/72

Response:

{
    "success": true,
    "data": {
        "id": 72,
        "partnerId": 225,
        "token": "ITFxuIUdY2",
        "status": 3,
        "credentialId": null,
        "title": "Connection by link for CRM Integration",
        "dateCreated": "2025-08-15 13:10:24"
    }
}

Important: Deleting a sharing entity sets the status to 3 (Token revoked). The token becomes permanently invalid and cannot be used for connection creation.

Step 7: List All Sharing Entities (Optional)

Retrieve all sharing entities for your account to manage multiple connection links.

Endpoint: GET /credentials/grant-access-sharing

Response:

{
    "success": true,
    "data": [
        {
            "id": 61,
            "partnerId": 225,
            "token": "aZeZWFwAQQ",
            "status": 1,
            "credentialId": 248,
            "title": "Connection by link for CRM Integration",
            "dateCreated": "2025-08-14 19:12:13"
        }
    ],
    "meta": {
        "page": 1,
        "totalPages": 1,
        "totalItemsCount": 1
    }
}

Best Practices

Security

Each token is single-use and becomes invalid after successful connection creation
Sharing links expire after 48 hours from creation
Tokens should be treated as sensitive information until used
Monitor sharing status regularly to detect completed connections

User Experience

Provide clear instructions to users about what they'll need to authenticate
Include the purpose and scope of the connection in the sharing title
Consider implementing polling to automatically detect when connections are ready

Error Handling

Check for status 3 (Token revoked) to handle cancelled or deleted connections
Implement appropriate timeouts for connection completion
Provide users with alternative connection methods if link-based connection fails
Use the update endpoint to regenerate tokens for expired or compromised links
Use the delete endpoint to clean up unused sharing entities and revoke access

Next Steps

Once a connection is successfully created (status = 1), you can:

Use in Solution Installation - Reference the credentialId when installing solutions
Use with Universal API - Include the credentialId in trigger/action requests
Manage Connection - Update or modify connection settings as needed

For more information on using connections with solutions, see the Solution Installation Guide.

For Universal API usage, see the Universal API Guide.