Log in as an investor via API

If you want investors to log in using Securitize ID and securely share their information with your platform, you’ll need to follow the OAuth authentication process. Don’t worry — we’ve broken it down into simple, step-by-step instructions to help you along the way! 😊

🚀 Step 1: Start the Authentication Process

👉 Add a Login Button or Image

Add a login image or button to your website that directs users to this URL:

Feel free to use this image:

https://id.{environment}.securitize.io/#/authorize?client_id={client_id}&scope={SCOPE}&redirect_uri={redirect_url}

🔑 Parameters:

• client_id: Your application’s client ID provided by Securitize (same as your domainId or issuerId).
• scope: The level of data access you need. Supported scopes:
  • info – Basic information like name, email, and address.
  • details – KYC status, suitability, accreditation.
  • verification – Account verification and suitability checks.

👉 Example:

scope=info details verification

• redirect_uri: The URL you want to send users to after login.
  ⚡️ Important: This URL must be whitelisted in your Securitize configuration.
  👉 Learn how to whitelist your URL here.

✅ Step 2: Handle the Redirect Response

The investor will be redirected to your URL with this information appended:

?code={token}&country={country_code}&authorized={true|false}

What These Parameters Mean:

• code: A temporary token (changes every time). You’ll use this to request the investor’s access token in the next step.
• country: The investor’s country code.
• authorized: Indicates whether the investor has previously agreed to share data.
  • true = investor already agreed
  • false = investor is logging in for the first time

🔄 Step 3: Exchange the Code for an Access Token

Use the /authorize endpoint to get the investor’s access token:

curl --location 'https://connect-gw.{environment}.securitize.io/api/auth/v1/authorize' \
--header 'clientid: {client_id}' \
--header 'Authorization: Bearer {secret}' \
--header 'Content-Type: application/json' \
--data '{
"code": "{code}"
}'

🔑 Parameters:

• client_id: Your application’s client ID provided by Securitize.
• Authorization: Your application secret provided by Securitize.
• code: The token received in Step 2.

🎉 Step 4: Review the Response

If successful, you’ll receive a 200 response like this:

{
  "investorId": "607f29dc3073230011ff018c",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "expiration": "2021-06-18T20:25:21.902Z"
}

✅ You’ve Now Completed the Login Journey!

You can use this access token to make API calls on behalf of the investor.

⚡ Note: Each code can only be used once. If you try to reuse it, you’ll get a 401 error.

👉 If you still need to whitelist your URL, follow this guide: How to whitelist your domain.

🗺️ Visual Guide

Here’s a quick diagram of the full login flow:

🛠️ Troubleshooting

Problem: OAuth Link Doesn’t Load Properly

If you open the OAuth link (id.{environment}.securitize.io) and see a broken page like this:

💡 Cause:
Your redirect URL isn’t correctly whitelisted in Securitize’s system.

👉 Solution:
Double-check your whitelisted URLs. Make sure the URL you’re using is included in your redirectUrls list with the wildcard symbol (*) at the end.

👉 Learn more about whitelisting your URL here.