Authentication¶

Python SDK V3 New

This authentication guide is for Nubra Python SDK 0.4.5 and the V3 trading flow.

To test V3 payloads, initialize the SDK with trading_version=TradingAPIVersion.V3 after authentication is configured.

Authentication creates a logged-in SDK session that can be reused across instruments, market data, portfolio, and trading classes.

Use this page when you need to:

initialize the SDK for V3 testing or for a production environment that supports the same flow
log in with OTP and MPIN
set up and use TOTP login
set up and use institutional login
use .env values for repeatable local workflows
reset or disable an existing auth setup

LLM guidance

Treat authentication as a process-level prerequisite, not a per-request action. Initialize the SDK once, then reuse the authenticated client across instruments, market data, and trading workflows.

Basic Usage¶

The default login flow uses your phone number, OTP, and MPIN.

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv
from nubra_python_sdk.trading.trading_enum import TradingAPIVersion

# Use NubraEnv.UAT for V3 testing and enable Trading API V3 explicitly.
nubra = InitNubraSdk(
    NubraEnv.UAT,
    env_creds=True,
    trading_version=TradingAPIVersion.V3,
)

# Reuse the authenticated client across modules.
# Example:
# instruments = InstrumentData(nubra)
# market_data = MarketData(nubra)
# trader = NubraTrader(nubra)

If you want to fully reset the session:

nubra.logout()

SDK Surface¶

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

InitNubraSdk(
    env: NubraEnv,
    totp_login: bool = False,
    env_creds: bool = False,
    insti_login: bool = False,
    trading_version: Optional[TradingAPIVersion] = None,
)

For V3 payload testing on 0.4.5, pass trading_version=TradingAPIVersion.V3 when initializing the client.

V3 enablement

trading_version=TradingAPIVersion.V3 activates the Sentinel/V3 trading surface in the SDK.

Trading requests also require the account-side Sentinel/OMS flag to be enabled by Nubra. If the account is not enabled yet, the client will not reach the V3 trading backend even if the SDK is initialized with the V3 trading flag.

Session helpers exposed on the initialized client include:

logout()
totp_generate_secret()
totp_enable()
totp_disable()

Authentication Modes¶

Mode	Trigger	User inputs	Best use case
OTP login	`totp_login=False`	phone number, OTP, MPIN	default onboarding flow
TOTP login	`totp_login=True`	phone number, TOTP, MPIN	repeated or semi-automated usage
Institutional login	`insti_login=True`	exchange client code, client code, username, password, MPIN	institutional account access
`.env` assisted	`env_creds=True`	env vars plus OTP or TOTP where needed	local scripts and repeatable dev flows

The standard OTP flow requires:

your registered phone number
the OTP received on that number
your MPIN

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

nubra = InitNubraSdk(NubraEnv.PROD)

After initialization, the SDK will prompt for the required login inputs.

TOTP is useful for repeated or more automation-friendly login flows.

TOTP Setup and Login Flow

This is a complete multi-step setup flow. Do not stop after generating the secret.

Step 1. Generate TOTP Secret

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

setup_client = InitNubraSdk(NubraEnv.PROD)
secret = setup_client.totp_generate_secret()
print("TOTP Secret:", secret)

Add the returned secret to your authenticator app.

Step 2. Enable TOTP

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

setup_client = InitNubraSdk(NubraEnv.PROD)
setup_client.totp_enable()

This flow prompts for the TOTP value and MPIN.

Step 3. Login Using TOTP

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

nubra = InitNubraSdk(NubraEnv.PROD, totp_login=True)

The SDK will prompt for the phone number, TOTP, and MPIN, then create the authenticated session.

Step 4. Disable TOTP

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

nubra = InitNubraSdk(NubraEnv.PROD)
nubra.totp_disable()

Institutional login is available through insti_login=True in InitNubraSdk.

Use this mode when the account authenticates with:

exchange client code
client code
username
password
MPIN

Basic institutional initializer:

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

nubra = InitNubraSdk(NubraEnv.PROD, insti_login=True)

If you want the SDK to read institutional credentials from a local .env file, enable env_creds=True.

Expected .env keys for institutional login:

CLIENT_CODE="..."
EXCHANGE_CLIENT_CODE="..."
USERNAME="..."
PASSWORD="..."
MPIN="..."

Institutional login flow in the current SDK:

the SDK creates or loads a device ID
it authenticates with exchange_client_code, client_code, username, and password
it then verifies MPIN
after MPIN verification, the session token is stored and reused by the SDK client

The SDK also exposes reset_password() for institutional clients after authentication.

Using .env Variables¶

For local scripts, you can keep the phone number and MPIN in a .env file instead of hardcoding them in code.

Example .env:

PHONE_NO="0000000000"
MPIN="0000"

Login with .env values enabled:

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

nubra = InitNubraSdk(NubraEnv.PROD, env_creds=True)

Session Behavior¶

Authentication creates a reusable session for the initialized client.

Reuse the same nubra client across SDK modules
Avoid re-initializing authentication for every small task
Use logout() when you intentionally want to clear the active session

Important Rules

Use NubraEnv.UAT for testing and NubraEnv.PROD for live usage.
Keep the environment explicit in code. Do not rely on assumptions about the active environment.
For SDK 0.4.5, initialize with trading_version=TradingAPIVersion.V3 when you want to test V3 payloads.
logout() resets the active session, so the next initialization may require the full authentication flow again.
OTP and TOTP login are session-setup flows, not per-request actions.
Institutional login is enabled through insti_login=True and still requires MPIN verification after password-based authentication.
Do not hardcode phone numbers, MPIN values, or TOTP secrets in source code.
Prefer env_creds=True for local repeatable workflows where .env is available.
After authentication, reuse the initialized client across reference-data, market-data, portfolio, and trading modules.

What To Read Next¶

After authentication, the most common next pages are: