Build your own integration

Build an integration when your product needs to create links, manage workspace resources, record conversions, or configure webhooks for Biqli users. OAuth lets each user approve access to one workspace without sharing an API key. Use a workspace API key for an internal service that manages only your own workspace. Use OAuth when other Biqli users connect their workspaces to your product.

How the connection works

You create an OAuth application in Biqli.
Your product sends the user to Biqli with the scopes it needs.
The user signs in, reviews the permissions, and selects a workspace.
Biqli returns a short-lived authorization code to your callback URL.
Your product exchanges the code for an access token and refresh token.
API requests run only inside the approved workspace and scopes.

1. Create an OAuth application

Open Workspace settings → OAuth Apps and select Create OAuth app. Add a recognizable name, developer details, an install URL, and every callback URL your product uses. Callback URLs are exact-match values. Production URLs must use HTTPS; HTTP is accepted only for localhost and loopback development. Choose Allow PKCE when the client cannot protect a secret, including browser, mobile, and desktop applications. Creating the application does not reveal its initial client secret. Open the saved application’s menu and select Regenerate secret when you are ready to store a new one-time value in a server-side secret manager.

Never place a client secret in browser code, a mobile or desktop bundle, a public repository, a URL, or a log.

For dashboard field behavior and application management, read Manage OAuth applications.

2. Choose a client type

Client	Authentication	Use when
Confidential	Client ID and client secret	A trusted server performs the token exchange and refresh.
Public	Client ID and S256 PKCE	Browser, mobile, or desktop code cannot keep a secret private.

PKCE uses a fresh high-entropy verifier for each authorization. Send its base64url-encoded SHA-256 challenge during authorization and the original verifier during the code exchange. Read the authorization request reference for the exact parameter contract.

3. Redirect the user to Biqli

Create an unpredictable state value, store it in the user’s session, and send the user to the authorization endpoint:

https://biq.li/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback&response_type=code&state=RANDOM_STATE&scope=workspace.read%20links.view

Request only the permissions the integration needs. Biqli displays those permissions before the user chooses a workspace and approves the connection. After approval, Biqli returns code and the unchanged state to the registered callback URL. Verify state before exchanging the code. Authorization codes expire after five minutes and can be used only once. If the user declines, the callback receives error=access_denied, an error_description, and the original state.

4. Exchange the authorization code

For a confidential client, exchange the code from your server:

curl --request POST \
  --url https://biq.li/api/v1/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'redirect_uri=https://app.example.com/oauth/callback' \
  --data-urlencode 'code=AUTHORIZATION_CODE'

Public clients omit client_secret and include the original code_verifier. Biqli accepts only the S256 PKCE method. A successful response returns a bearer access token, its lifetime, a refresh token, the refresh-family lifetime, and the granted scope string. Store tokens server-side when the client architecture allows it. See Exchange or refresh a token for complete request, response, and error behavior.

5. Confirm the connection

Call GET /api/v1/oauth/me before saving the installation:

curl https://biq.li/api/v1/oauth/me \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

The response identifies the user and selected workspace. Store the public connection ID and workspace ID with your installation record. Do not ask the user to type an internal workspace identifier. Read Retrieve the connected workspace for the response contract.

6. Make an API request

Use the access token as a bearer credential. For example, list links in the connected workspace:

curl --request GET \
  --url 'https://biq.li/api/v1/link?page_size=10' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

The token selects the connected workspace and its scopes control the available operations. Workspace roles, resource policies, plan entitlements, and quotas still apply after authorization. Use the endpoint pages under API Reference for request and response contracts. The scope reference maps OAuth permissions to those operations.

7. Refresh tokens safely

Access tokens are short-lived. Exchange the current refresh token before the access token expires and atomically replace both stored tokens with the new values. Every successful refresh rotates the refresh token. Reusing an older refresh token revokes the entire token family, including the newest access token. Do not retry with a token that may already have succeeded in another worker.

8. Revoke disconnected installations

When a user disconnects your integration, send the current access or refresh token to POST /api/v1/oauth/revoke, then remove the local credentials. Revocation invalidates the connection. Webhook endpoints created by that OAuth connection are removed automatically. Removing the OAuth application revokes all of its connections. See Revoke a connection for the exact request contract.

Add webhooks when you need events

Use webhooks instead of polling when your integration reacts to link, click, lead, or sale activity. Request only the webhook permissions you need, store the endpoint signing secret securely, verify the exact raw request body, and deduplicate events by their envelope ID. Start with the webhook introduction. Use the webhook endpoint API to create, test, inspect, and remove endpoints from your integration.

Production checklist

Register every production callback URL exactly.
Generate and validate a fresh state for each authorization.
Use S256 PKCE for every public client.
Keep client secrets, access tokens, and refresh tokens out of logs.
Request the smallest granular scope set.
Verify /oauth/me before binding the installation locally.
Replace refresh tokens atomically after every successful refresh.
Reauthorize after invalid_grant; never replay a code or rotated token.
Revoke credentials when the user disconnects.
Test authorization, denial, refresh, revocation, and insufficient-scope paths.

For protocol failures, read OAuth errors.

GETTING STARTED

BROWSER TRACKING

MOBILE DEEP LINKING

SERVER TRACKING

INTEGRATIONS

OPERATIONS

Build your own integration

How the connection works

1. Create an OAuth application

2. Choose a client type

3. Redirect the user to Biqli

4. Exchange the authorization code

5. Confirm the connection

6. Make an API request

7. Refresh tokens safely

8. Revoke disconnected installations

Add webhooks when you need events

Production checklist

​How the connection works

​1. Create an OAuth application

​2. Choose a client type

​3. Redirect the user to Biqli

​4. Exchange the authorization code

​5. Confirm the connection

​6. Make an API request

​7. Refresh tokens safely

​8. Revoke disconnected installations

​Add webhooks when you need events

​Production checklist

How the connection works

1. Create an OAuth application

2. Choose a client type

3. Redirect the user to Biqli

4. Exchange the authorization code

5. Confirm the connection

6. Make an API request

7. Refresh tokens safely

8. Revoke disconnected installations

Add webhooks when you need events

Production checklist