Docs/aptr-connect SDK

aptr-connect SDK

Integrate Apertur into your application with the aptr-connect SDK. Allow your users to connect their Apertur account through a secure OAuth consent flow.

Overview

The aptr-connect SDK is a lightweight JavaScript library that handles the OAuth authorization flow between your application and Apertur. It uses a public key that is safe to expose in frontend code.

Prerequisites

A partner account on Apertur
An OAuth app created in your partner dashboard
At least one redirect URI configured

Installation

Add the SDK script to your HTML page. The script is hosted on the Apertur CDN and should be loaded before your integration code.

<script src="https://cdn.apertur.ca/sdk/aptr-connect.js"></script>

Initialization

Initialize the SDK with your public key. You can find your public key in the OAuth app settings of your partner dashboard.

AptrConnect.init({
  publicKey: "aptr_pk_your_key_here",
});

Public key security

The public key (aptr_pk_...) is designed to be exposed in frontend code. It can only be used to initiate the OAuth flow, not to access any data. For additional security, configure allowed domains in your app settings.

Authorization Flow

Call AptrConnect.authorize() to start the OAuth consent flow. This opens a popup window where the user can log in to Apertur and authorize your application.

AptrConnect.authorize({
  scopes: ["upload:create", "upload:read", "project:read"],
  redirectUri: "https://your-app.com/callback",  // Must match your app config
  onSuccess: (result) => {
    // result.code — authorization code to exchange server-side
    // result.state — CSRF state parameter (if provided)
    sendToBackend(result.code);
  },
  onError: (error) => {
    console.error("Authorization failed:", error.message);
  },
});

Available Scopes

Scope	Description
plan:read	Read plan details (always included)
upload:create	Create upload sessions
upload:read	Read upload history
project:read	Read project information
project:settings	Modify project settings
keys:read	Read API keys
webhooks:manage	Manage event webhooks
billing:read	Read billing information

Exchanging the Code

After the user authorizes, your frontend receives an authorization code. Exchange it for an access token server-side using your client secret (never expose the client secret in frontend code).

curl -X POST https://apertur.ca/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "code": "AUTH_CODE_FROM_SDK",
    "redirect_uri": "https://your-app.com/callback"
  }'

The response includes an access token:

{
  "access_token": "oat_xxxxxxxxxxxx",
  "token_type": "Bearer",
  "project_id": "...",
  "scopes": ["plan:read", "upload:create", ...],
  "plan": { "name": "Pro", ... }
}

Complete Example

<!DOCTYPE html>
<html>
<head>
  <title>Connect with Apertur</title>
  <script src="https://cdn.apertur.ca/sdk/aptr-connect.js"></script>
</head>
<body>
  <button id="connect-btn">Connect your Apertur account</button>

  <script>
    AptrConnect.init({ publicKey: "aptr_pk_your_key_here" });

    document.getElementById("connect-btn").addEventListener("click", () => {
      AptrConnect.authorize({
        scopes: ["upload:create", "project:read"],
        redirectUri: "https://your-app.com/callback",
        onSuccess: (result) => {
          // Send the code to your backend
          fetch("/api/apertur/connect", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ code: result.code }),
          });
        },
        onError: (err) => {
          alert("Connection failed: " + err.message);
        },
      });
    });
  </script>
</body>
</html>

Domain Restrictions

To prevent unauthorized use of your public key, configure allowed domains in your OAuth app settings. The SDK validates the Origin header of requests against your allowed domains list.

Pattern	Matches	Does not match
example.com	example.com	app.example.com
*.example.com	app.example.com, staging.app.example.com	example.com, other.com
*.localhost	app.localhost	localhost

Development tip

Leave the allowed domains list empty during development to allow requests from any origin. Add your production domains before going live.

Error Handling

Error	Cause	Solution
invalid_public_key	Public key not found or deactivated	Check the key in your partner dashboard
origin_not_allowed	Request origin doesn't match allowed domains	Add the domain to your app's allowed domains list
user_denied	User cancelled the authorization	Show a retry option to the user
popup_blocked	Browser blocked the popup	Ensure authorize() is called from a user gesture (click)