Unlok API

Company / Vendor Details

Provide the following information about your company:

{
  "companyName": "Acme Trading Corp",
  "companyWebsite": "https://acme-trading.com",
  "businessEmail": "dev@acme-trading.com",
  "country": "US",
  "phone": "+1-555-123-4567"
}

App Details

Provide the following information about the application you want to register:

{
  "appName": "Trading Bot Pro",
  "description": "Automated trading signals and portfolio management",
  "logoUrl": "https://acme-trading.com/logo.png",
  "homepageUrl": "https://acme-trading.com",
  "supportEmail": "support@acme-trading.com",
  "supportUrl": "https://acme-trading.com/support",
  "privacyPolicyUrl": "https://acme-trading.com/privacy",
  "termsOfServiceUrl": "https://acme-trading.com/terms",
  "redirectUris": ["https://acme-trading.com/callback"]
}

Generate PKCE Challenge

Before redirecting the user, generate a PKCE code verifier and challenge:

// Generate random code_verifier (43-128 characters)
const codeVerifier = generateRandomString(64);

// Create code_challenge (SHA-256 hash, base64url encoded)
const codeChallenge = base64url(sha256(codeVerifier));

// Store codeVerifier securely (session/cookie) — you'll need it later

Redirect to Authorization

Build the authorization URL and redirect the user:

const authUrl = new URL('https://api.unlok.com/oauth/authorize');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('client_id', 'ulk_cid_abc123');
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.set('scopes', 'orders:read,account:read');
authUrl.searchParams.set('state', generateRandomState());  // CSRF protection
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');

// Redirect user to Unlok
window.location.href = authUrl.toString();

Handle the Callback

After the user approves, Unlok redirects back to your redirect_uri with a code:

// Your callback URL receives:
// https://yourapp.com/callback?code=ulk_ac_xyz789&state=xyzABC123

// 1. Verify the state matches what you stored (CSRF protection)
// 2. Extract the code parameter

Exchange Code for Tokens

Call POST /oauth/token from your backend to exchange the code:

const response = await fetch('https://api.unlok.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'AUTH_CODE',
    code: 'ulk_ac_xyz789',
    redirect_uri: 'https://yourapp.com/callback',
    client_id: 'ulk_cid_abc123',
    client_secret: process.env.CLIENT_SECRET,
    code_verifier: storedCodeVerifier  // From step 1
  })
});

const { access_token, refresh_token, expires_in } = await response.json();

See the full API reference.

Make API Calls

Use the access token in the Authorization header:

const response = await fetch('https://api.unlok.com/api/orders', {
  headers: {
    'Authorization': `Bearer ${access_token}`
  }
});

Refresh Tokens

When the access token expires, use the refresh token to get a new one:

const response = await fetch('https://api.unlok.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'REFRESH_TOKEN',
    refresh_token: storedRefreshToken,
    client_id: 'ulk_cid_abc123',
    client_secret: process.env.CLIENT_SECRET
  })
});

const { access_token, refresh_token } = await response.json();
// Store the new refresh_token — it replaces the old one