Getting API Keys / Access Tokens

Create, manage, and secure API credentials

Create an API Key

Step 1: Log in to Developer Portal

Go to https://developers.ssi.com.vn and log in with your SSI account.

Step 2: Create a New API Key

Navigate to Dashboard -> API Key Management -> Create New Key

Name your API Key (e.g., "Trading Bot Production")

Click Create -> Save immediately both API Key and API Secret

Important: The API Secret is displayed ONLY ONCE. If lost, go to the API Key details page to view it again.

Authentication with API Key

FastConnect uses Bearer token authentication. The flow:

1. Get an Access Token

Call /api/v3/auth/token with your API Key and API Secret:

curl -X POST "https://api.ssi.com.vn/api/v3/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_api_key",
    "apiSecret": "your_api_secret"
  }'

Response:

{
  "tokenType": "Bearer",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
  "expiresAt": 1779806203,
  "refreshExpiresAt": 1779892603
}

2. Use the Access Token

Pass the token in the Authorization header for all API calls:

curl -X GET "https://api.ssi.com.vn/api/v3/data/securitiesByBoard?board=HOSE" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

3. Refresh the Token

When the access token expires, use the refresh token:

curl -X POST "https://api.ssi.com.vn/api/v3/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "dGhpcyBpcyBhIHJlZnJl..."
  }'

To place/modify/cancel orders, the access token must be issued with an otp or transactionId when calling /api/v3/auth/token. How you obtain this value depends on the account's 2FA type — there are 3 scenarios:

Scenario 1: OTP via SMS/Email

Applies to accounts using 2FA type SMS or Email. The OTP is sent to the registered phone number/email after calling requestOtp.

# Step 1: Request an OTP via SMS/Email
curl -X POST "https://api.ssi.com.vn/api/v3/auth/requestOtp" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_api_key",
    "apiSecret": "your_api_secret"
  }'
# Response: { "message": "Success" }

# Step 2: Enter the OTP received via SMS/Email into the otp parameter
curl -X POST "https://api.ssi.com.vn/api/v3/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_api_key",
    "apiSecret": "your_api_secret",
    "otp": "123456"
  }'

Scenario 2: OTP directly from the iBoard app (SmartOTP)

Applies to accounts using 2FA type SmartOTP. No need to call requestOtp — open the iBoard app, go to the SmartOTP section to get the currently displayed code, and pass it directly into the otp parameter.

curl -X POST "https://api.ssi.com.vn/api/v3/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_api_key",
    "apiSecret": "your_api_secret",
    "otp": "482913"
  }'

Scenario 3: OTP via the Mobile Approval flow

Also applies to accounts using 2FA type SmartOTP, but the customer approves the request directly in the app instead of entering a code.

Note 1: The transactionId is valid for 30 seconds. The customer must approve the request on the iBoard mobile app within 30 seconds to complete this 2FA process.

Note 2: To automate your application without manually entering an OTP every day, we recommend implementing this Mobile Approval flow.

# Step 1: Send an approval request to the iBoard app
curl -X POST "https://api.ssi.com.vn/api/v3/auth/requestOtp" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_api_key",
    "apiSecret": "your_api_secret"
  }'
# Response:
# {
#   "message": "Please approve the login request via the iBoard mobile app.",
#   "transactionId": "f306c510-0647-417b-9210-bb5b7e155e77"
# }

# Step 2: The customer opens the iBoard app and taps Approve

# Step 3: Call the token endpoint with the transactionId obtained in Step 1 (no otp needed)
curl -X POST "https://api.ssi.com.vn/api/v3/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_api_key",
    "apiSecret": "your_api_secret",
    "transactionId": "f306c510-0647-417b-9210-bb5b7e155e77"
  }'

You can find sample implementations for the SmartOTP Mobile Approval flow in the Tutorials section.

Test thoroughly with the new key

Delete the old key

Delete a Key

Delete immediately if:

The key has been exposed
No longer in use
Needs to be replaced with a new key

Security Best Practices

DO

Store keys in environment variables or a secret manager
Use HTTPS for all requests
Rotate keys periodically
Create separate keys for each application
Monitor API usage to detect anomalies

DON'T

Commit keys to Git/GitHub
Hardcode keys in source code
Share keys via email/chat
Use Production keys for testing
Share a single key across multiple applications

Next Steps

Got your API Key? Continue with First API Call!