Build · Integrate · Unlok

Include the following about your company:

• Company Name - Your registered business name (e.g. Acme Trading Corp)
• Company Website - Your company's website URL (e.g. https://acme-trading.com)
• Business Email - A contact email for your team (e.g. dev@acme-trading.com)
• Country - Your 2-letter country code (e.g. US, GB, SG)
• Phone (optional) - A contact phone number

Tell us about the application you'd like to integrate:

• App Name - A display name for your application (e.g. Trading Bot Pro)
• Description (optional) - A short summary of what your app does
• Logo URL - A publicly accessible URL to your app's logo
• Homepage URL - Your app's public homepage
• Support Email - Where users can reach your support team
• Support URL (optional) - Link to your support/help center
• Privacy Policy URL - Link to your privacy policy
• Terms of Service URL - Link to your terms of service
• Redirect URIs - One or more callback URLs where users will be redirected after authorization (e.g. https://acme-trading.com/callback)
• Scopes Requested - The API permissions your app needs. You will only be able to request scopes that have been approved for your app. Available scopes:
  • read:accounts - Read account details and profile
  • write:accounts - Update account settings
  • read:orders - View orders and trade history
  • write:orders - Place and manage orders
  • read:banking - View banking and funding details
  • write:banking - Manage banking and funding

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

Build the authorization URL pointing to the Unlok login page and redirect the user. Include the scopes your app needs as a comma-separated list:

// The entry point is the Unlok login page - not the /oauth/authorize API directly.
// The login page handles authentication and then presents the consent screen.
const authUrl = new URL('https://join.unlok.com/en/login');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('client_id', 'your_client_id');
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.set('scopes', 'read:accounts,read:orders');  // comma-separated
authUrl.searchParams.set('state', generateRandomState());  // CSRF protection
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');

// Redirect the user's browser to Unlok
window.location.href = authUrl.toString();

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

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.

Use the access token in the Authorization header. For example, fetch the authenticated user's profile from GET /oauth/userinfo (requires the read:accounts scope):

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

const { userId, email, firstName, lastName } = await response.json();

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