Sandbox and authentication

Base URL

Get a token

curl -X POST "https://partners-api.sandbox.securitize.io/oauth2/token" \
  -d grant_type=client_credentials \
  -d client_id="$SECID_CLIENT_ID" \
  -d client_secret="$SECID_CLIENT_SECRET"

{ "token_type": "bearer", "access_token": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "expires_in": 7200 }

curl "https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance/investors?limit=1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

• The token lasts 2 hours (expires_in, in seconds). Cache it and get a new one shortly before it expires, or on the first 401. Do not request one per call.
• No scope. Send none.
• In the Authorization header only. Never put the token in a URL: URLs end up in logs.
• The token identifies your partner account. You never send a partner or tenant id, and every record you create is scoped to your account: your identifiers cannot collide with another partner’s. Another partner’s investor answers 404, as if it did not exist.

const HOST = 'https://partners-api.sandbox.securitize.io';
const BASE = `${HOST}/investors/v1/onboarding-reliance`;

let cached = { token: null, expiresAt: 0 };

async function accessToken() {
  if (Date.now() < cached.expiresAt - 60_000) return cached.token;
  const res = await fetch(`${HOST}/oauth2/token`, {
    method: 'POST',
    headers: { 'content-type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.SECID_CLIENT_ID,
      client_secret: process.env.SECID_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`token: ${res.status}`);
  const { access_token, expires_in } = await res.json();
  cached = { token: access_token, expiresAt: Date.now() + expires_in * 1000 };
  return access_token;
}

const investors = await fetch(`${BASE}/investors?limit=1`, {
  headers: { authorization: `Bearer ${await accessToken()}` },
}).then((r) => r.json());
console.log(investors.meta);

import os, time, requests

HOST = "https://partners-api.sandbox.securitize.io"
BASE = f"{HOST}/investors/v1/onboarding-reliance"
_cached = {"token": None, "expires_at": 0.0}


def access_token() -> str:
    if time.time() < _cached["expires_at"] - 60:
        return _cached["token"]
    res = requests.post(f"{HOST}/oauth2/token", data={
        "grant_type": "client_credentials",
        "client_id": os.environ["SECID_CLIENT_ID"],
        "client_secret": os.environ["SECID_CLIENT_SECRET"],
    }, timeout=10)
    res.raise_for_status()
    body = res.json()
    _cached.update(token=body["access_token"], expires_at=time.time() + body["expires_in"])
    return _cached["token"]


investors = requests.get(f"{BASE}/investors", params={"limit": 1},
                         headers={"Authorization": f"Bearer {access_token()}"}, timeout=10).json()
print(investors["meta"])

Keeping secrets and data safe

• The client secret is a secret: keep it in a secrets manager, inject it at runtime, and ask Securitize to rotate it at once if it is exposed. Never put it in source control, scripts or client-side code. Treat the access token the same way while it lives.
• Keep separate credentials for sandbox and production, so production credentials can never reach the sandbox URL or the reverse.
• Call the API from your backend only.
• Identity documents are personal data: never log request bodies with content; log the document id and type from the response instead.
• The correlationId holds no personal data and is safe to log and to share with Securitize support.

When the token is wrong

How sandbox behaves

• Synthetic data only. Sandbox validates requests like production and sends identity documents to a test identity provider. Use @test.invalid emails and invented names and identifiers.
• Documents must be complete image files. A truncated or corrupt file is refused with 422 document_rejected. Use the test files.
• Identifiers must change between runs. An externalInvestorId, tax identifier or email you already used belongs to an existing investor: the same body returns that investor, different data answers 409. Generate fresh values for every test run, including when you copy the examples in these docs.
• Every submitted investor ends verified. Sandbox does not produce manual-review, rejected or updates-required, and does not check a US person’s tax identifier against their name and address; build those branches from Statuses.
• When verified arrives depends on your agreement. Depending on your integration agreement with Securitize, an investor becomes verified as soon as the verification is submitted, or once Securitize’s screening answers. Requests and responses are the same in both cases; build your integration to poll until the status leaves processing.