Authentication
Send the token with every request, see what it allows and fix a refused request.
Every request carries the terminal's token. The token allows everything the terminal window can do, including placing orders.
Send the token
curl -H "Authorization: Bearer $SPECTRE_LOCAL_API_TOKEN" http://127.0.0.1:48180/v1/metaThe token is spt_ followed by 64 hex characters. It goes only in the
Authorization: Bearer header, both for HTTP requests and for the WebSocket
handshake. A token in the URL is not accepted.
The clients add the header for you and keep the token out of error messages and logs. To copy the token, see Get the token.
See what the token allows
meta = terminal.meta()
print(meta.scopes)A call needs the scope of its area, and the token has all of them. There is no separate switch for trading: the Local API switch is the only one.
| Scope | What it allows |
|---|---|
market:read | Read market data. Open the stream. |
connections:read | Read the connections. |
account:read | Read orders, positions, balances, fills and leverage. |
trading:write | Place and cancel orders and trigger orders. Close positions. Set leverage and the margin mode. |
workspace:read | Read the layout. |
workspace:write | Open, close and select stacks, tabs and windows. |
settings:read | Read settings. |
settings:write | Change settings. |
A read scope also covers the stream topics of its area. meta() and
health() work with any valid token. An older terminal lists only the scopes
it has.
When a request is refused
| What happens | What you get | What to do |
|---|---|---|
| No token, a wrong token, or the API is off | 401 unauthorized | Copy the current token and check that the API is on |
The request has an Origin header, as browser pages send | 403 forbidden | Call from a script or a program |
The address is not 127.0.0.1 or localhost | 403 forbidden | Use 127.0.0.1 |
| The token lacks the scope of the call | 403 forbidden_scope | Check meta().scopes and update the terminal |
The clients raise ApiError with the same code. All codes are in
Errors.
Replace the token
Press Reissue token in Settings App → General → Local API. The old
token stops working at once: requests get 401, and open streams are closed
with code 1001.
The terminal has one token, so every program that uses the API needs the new one.
Keep the token safe
Keep the token in the environment of the program that needs it, or in a secrets store. Keep it out of source code, committed config files and chats. If it leaks, reissue it.
The API never returns exchange keys, not even masked.