Elevated Access | NinjaTrader Partner API

A session can read and change a user’s personal information only while it has elevated access for that user. Partner SSO sessions work the same way. This page explains how to detect that a session needs elevated access and how to obtain it.

These endpoints are Live-only. Do not send them to the Demo base URL.

At a Glance

Personal information is available only to an elevated session. Until a user has granted elevated access, a session can’t read or change that user’s personal information. The failure doesn’t always look like an error: some calls return HTTP 401, some succeed with personal details blank or hidden, and some return HTTP 200 with a message in errorText.
A user grants elevated access with a six-digit code NinjaTrader sends by email. Your backend submits the code, and the access lasts 30 days.
Some users don’t need a code. Call sensitivityProbe first, and request a code only when it returns the HTTP 401 that says an additional authentication step is required.

Without Elevated Access

For a customer user:

Contact records come back without the street address, city, postal code, and phone number.
Employment details are hidden.
Calls that change contact information (updateContactInfo, updateContactCountry, and updateContactInfoName) return HTTP 401.
Some document management calls need elevated access, for example prepareAgreementDocuments, getAgreementDocument, and signAgreementDocuments, because they read agreement documents and applicant details.

For an organization administrator, elevated access isn’t required, because they can read personal information without it. A denied probe for an organization administrator isn’t caused by missing elevation, and doesn’t necessarily mean that personal information is blocked.

What a Failure Looks Like

Calls that need personal information don’t all fail the same way.

Call or situation	What you see
`sensitivityProbe` and the contact information changes above, without elevated access	`HTTP 401` with the message `Access requires an additional authentication step. Please upgrade.`
`sensitivityProbe` and the contact information changes above, when your app is denied personal information access	`HTTP 401` with the message `Access is denied`
Calls that return records with personal details, such as contact information, without elevated access	A successful response with the street address, city, postal code, and phone number blank, and employment details replaced with `<hidden>`
Document management calls that read agreement documents or applicant details, without elevated access	The data isn’t returned. Depending on the call, you can get an empty result or a normal `HTTP 200` response with a message in `errorText`

Because a failure doesn’t always look like an authorization error, use sensitivityProbe to find out whether a session is elevated instead of waiting for a call to fail. An empty result, or a message saying something wasn’t found, can mean the user hasn’t granted elevated access, not that the record is missing.

Elevated access applies to one user in your integration. Each user grants it separately, and granting it for one user doesn’t affect another.

Elevated access is recorded for a user on a specific device ID, and a code works only for the device ID of the session that requested it. Partner SSO sessions get one fixed device ID per user, so you don’t manage it.

How Elevation Works

Call sensitivityProbe and read the response.
If the response is an HTTP 401 that says an additional authentication step is required, call requestElevation. NinjaTrader emails the user a six-digit code.
Collect the code from the user in your own interface, then call submitElevationCode from your backend.
Repeat the call from step 1. The user now has elevated access for 30 days.

Elevation doesn’t require a new access token. Keep using the token you already have, and don’t sign the user in again. Open WebSocket connections are the one thing that needs attention, because they have to reconnect with that same token.

Checking Whether a Session Needs Elevated Access

sensitivityProbe changes nothing. It succeeds only when the session can reach personal information, so use it to decide whether to start the elevation flow. Other calls can fail without an HTTP 401, so don’t wait for one.

curl -sS -X POST "https://live.tradovateapi.com/v1/auth/sensitivityprobe" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment": "elevation check"}'

An elevated session gets HTTP 200:

{
  "ok": true
}

A session without elevated access gets HTTP 401 with this message:

Access requires an additional authentication step. Please upgrade.

Some users are elevated without a code, depending on their account and device history. This automatic access can end sooner than 30 days, so probe each time instead of assuming a user stays elevated. A probe that returns HTTP 200 means you can skip the rest of the flow for that user, so always probe first.

Requesting the Code

Call requestElevation after the probe returns the HTTP 401.

curl -sS "https://live.tradovateapi.com/v1/access/requestelevation" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "ok": true
}

requestElevation returns "ok": true whether or not an email goes out, so a successful response doesn’t confirm delivery. If the user doesn’t receive an email after a short wait, call requestElevation again. If a second request still brings no email, contact your NinjaTrader representative.

The email carries a six-digit code that can be used once and is valid for one hour. Codes from earlier requests stay valid until they expire.

Submitting the Code

Send the six digits without any spacing. The email shows them split into two groups of three.

curl -sS -X POST "https://live.tradovateapi.com/v1/access/submitelevationcode" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

A matching code returns "ok": true and gives the user elevated access for 30 days. A code that doesn’t match returns HTTP 200 with "ok": false and an errorText explaining why, and the user can re-enter the code or request a new one.

{
  "errorText": "…",
  "ok": false
}

Elevated access can take a short time to reach your session, so a REST call sent immediately afterward can still return the HTTP 401. Retry after a short pause before treating it as a failure.

When elevated access expires, the probe returns the HTTP 401 again and the same flow applies.

WebSocket Sessions

A WebSocket connection keeps the access level it had when it connected, so granting elevated access doesn’t raise the access level of a connection that is already open. NinjaTrader can close the user’s connections that have sent user/syncrequest when elevated access is granted. Other connections stay open at their previous access level, with personal information hidden, until you open a new connection.

Don’t wait for a disconnect. Submit the code over REST, then reconnect every WebSocket connection for that user with the same access token. You don’t need a new token.

Rate Limits

submitElevationCode is rate limited by IP subnet, and only failed attempts count. When you exceed the limit, the response is a penalty ticket instead of the usual response body, so it has no ok field. Validate that the code is six digits before you submit it, and don’t retry a wrong code automatically.

Each requestElevation call emails the user another code, so don’t call it in a loop while you wait for the email.

For the limit and how to recover, see Rate Limits and Penalty Tickets.

Denying Personal Info Access to Elevated Sessions

By default, an elevated session has access to the user’s personal information. You don’t need to request or configure anything beyond elevated access.

NinjaTrader can deny personal information access to elevated sessions for your app. In that case, sensitivityProbe and the calls that change contact information return HTTP 401 with this message, both before and after elevation:

Access is denied

Calls that return personal details behave as they do for a session without elevated access, with details blank or hidden, or a message in errorText in a normal response. If a call for something else starts returning HTTP 401 with “Access is denied” after the change, tell your NinjaTrader representative.

An app set up this way can still request and submit codes, and submitElevationCode still succeeds. A successful submission doesn’t prove the app can reach personal information, so confirm with sensitivityProbe.

A change to your app’s personal information access reaches your REST calls on its own, but a WebSocket connection that is already open keeps its previous access until it reconnects.

To turn personal information access off (or back on) for an app, contact your NinjaTrader representative and tell them which app.

Testing

Test with pilot users on the staging Live URL, https://live-api.staging.ninjatrader.dev/v1 (see Environments), before go-live. The examples on this page use the production host, so replace it with the staging host when you test. Cases worth exercising:

Case	Expected
A user who already has elevated access	`sensitivityProbe` succeeds, and no code is needed
A user who doesn’t have elevated access	`sensitivityProbe` returns `HTTP 401` saying an additional authentication step is required
`requestElevation` for that user	`"ok": true`, and the user receives an email with a six-digit code
`submitElevationCode` with the correct code	`"ok": true`, and `sensitivityProbe` then succeeds (retry after a short pause if the first call returns `HTTP 401`)
`submitElevationCode` with a wrong code	`HTTP 200` with `"ok": false` and an `errorText`
An app with personal information access denied to elevated sessions	`sensitivityProbe` returns `HTTP 401` saying access is denied, before and after elevation
A WebSocket that sent `user/syncrequest` before elevated access was granted	The connection may close, and a reconnect with the same access token works
A WebSocket that never sent `user/syncrequest`	The connection stays open at its previous access level, with personal information hidden, until you reconnect

Next Steps

Partner Token: the assertion exchange that creates a partner session.
SSO with ShortGrantCode: send a signed-in user to a NinjaTrader-hosted page.
Penalty Tickets: how the time-penalty response works and how to recover.
WebSocket Connection Overview: reconnect after elevated access is granted.