Note: This help page is currently being updated to recommend the use of SHA256/512 instead of MD5 and TOTP as the 2nd Factor.
Any references to MD5 should be read as SHA256/512 and any references to 2FA by SMS should be read as by TOTP.
You can authenticate using a logon/password combination or get a secure access token
If you are not using a secure access token – then you need to authenticate via the logon endpoint (/rpc/logon)
If you are using a “user-agent” like a web-browser that supports cookies, then the session ID will be stored automatically and used for subsequent requests (POSTs) – if the “user-agent”/client does not support cookies then you need to record the returned session ID (sid) and logonKey and append it to each subsequent request – eg &sid=[sid]&logonkey=[logonkey returned by LOGON method].
You can also use "auth-" http headers to pass the authentication data - see the "HTTP HEADERS" section on this page.
To authenticate you need to POST to /rpc/logon/:
It is best practice to POST (not GET) all requests via https (not http) to ensure all data is encrypted and use passwordhash.
|TYPICAL AUTHENTICATION (LOG ON) FLOW
|USER PASSWORD (SETUP_SPACE_SETTINGS_MANAGE)
|TRUSTED PRIVILEGED ACCESS TOKENS
|If you need to authenticate an user on a secure device that you have limited control over and you can not use the logon process described above, then you can use an access token.
You can generate a token for a user using:
You can then pass the generated token as &access_token= with each API call.
Access tokens can be disabled as and when required.
Security note: Given that this token gives privileged access (outside of the multi-token authorisation process), make sure you protect this token and be wary of using it in the URL query string, as data in the query string is not encrypted during transmission (even if using SSL). It is recommended that the user associated with this token has limited access to methods.
|USING HTTP HEADER
You can use http headers to pass the authentication data.