Guides

Initiating a Connection

Suggest Edits

To set up an embedded connection within your application, you must start by generating a redirect URL using the Ragie API. This establishes trust between your application and Ragie and the redirect URL allows Ragie to associate the connection with your Ragie account. To do this, call the oauth initialization API:

curl https://api.ragie.ai/connections/oauth \
  -H "Authorization: Bearer $RAGIE_API_KEY" \
  --json '{"source_type": "google_drive", "redirect_uri": "https://example.com/link/to/your/application"}'

The only parameters required to generate the redirect URL are source_type which is the type of integration you would like to connect and the redirect_uri which is the URL that you would like to redirect the user back to in your application after they have finished connecting.

Optional parameters for establishing the connection include metadata, mode and partition. Below is an example showing how to add the optional parameters:

curl https://api.ragie.ai/connections/oauth \
  -H "Authorization: Bearer $RAGIE_API_KEY" \
  --json '{"source_type": "google_drive", "redirect_uri": "https://example.com/link/to/your/application", "metadata": {"user_id": "my-application-user-id"}, "mode": "hi_res", "partition": "my-application-tenant-id" }'

In this example, we add the user_id of the user in your application as metadata and we use the tenant id of your application for the partition. Both of these parameters can be used to filter during retrieval.

The response from this API will be a JSON object with the redirect URL:

{"url":"https://ragie.dev:3443/embed/connect?auth=eyJhb..."}

Once you have the Ragie redirect URL from the JSON response, redirect the user to the redirect URL and they will begin authenticating with the integration provider.

When the user has successfully authenticated and configured their connection in Ragie, they will be redirected back to your application’s redirect_uri with a connection ID that was created for this user. In this example the user will be redirected back to this url:

https://example.com/link/to/your/application?connection_id=5b1eadd0-700c-443d-bfa1-8f73a2f9f4d3

If an error occurred during authentication, then the user will be redirected back to your application’s redirect_uri with an error:

https://example.com/link/to/your/application?error=access_denied

Now that your connection has been established, you can use webhooks to monitor the sync.

Updated about 1 month ago

What’s Next