Authentication

Endpoints for checking and managing your Formlabs Dashboard account login state. Endpoints that call Formlabs web services need a login session, and say so in their descriptions.

Log in to a Formlabs Dashboard account#

POST/v1/login/

Authenticates with Formlabs Dashboard, either with a username and password or with a previously issued access token, and stores the resulting session for the lifetime of the PreFormServer process. Logging in again replaces any existing session.

Some endpoints call Formlabs web services on your behalf and require this login state. Use /v1/user/ to check whether a session is currently active, and /v1/logout/ to end it.

Error codes#

HTTP	`error.code`	Cause
400	`JSON_PARSE_ERROR`	The request body is not a valid JSON object.
400	`JSON_SCHEMA_MATCH_ERROR`	The body has neither a complete `username`/`password` pair nor an `access_token`, mixes the two shapes by including `access_token` alongside `username`/`password`, has a field with the wrong type, or contains an unrecognized field. The message names whichever problem applies.
400	`OPERATION_FAILED`	The credentials or access token were rejected by Formlabs Dashboard, or Dashboard could not be reached. The message carries the underlying reason.

Request bodyobject

Username and passwordoption 1 of 2
Show fields
- usernamestringRequired
  Formlabs Dashboard account username or email address.
- passwordstringRequired
  Formlabs Dashboard account password.
Access tokenoption 2 of 2
Show fields
- access_tokenstringRequired
  A previously issued Formlabs Dashboard access token.

ReturnsLoginResponse

access_tokenstringRequired
Access token for the newly created session.
refresh_tokenstringRequired
Refresh token for the newly created session. Empty when logging in with access_token rather than a username and password.

POST/v1/login/

Terminal

curl -X POST "http://localhost:44388/v1/login/" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jane@example.com",
    "password": "hunter2"
  }'

Terminal

curl -X POST "http://localhost:44388/v1/login/" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "e0f3a4b1c2d5e6f7"
  }'

Response

JSON

{
  "access_token": "e0f3a4b1c2d5e6f7",
  "refresh_token": "9a8b7c6d5e4f3a2b"
}

Log out of Formlabs Dashboard account#

POST/v1/logout/

Clears the current Dashboard login session, if any. Succeeds on both logout and the case where no one is logged in. Takes no request body.

Returnsno body

The session was cleared (or there was none to clear). The response has no body.

POST/v1/logout/

Python

from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    preform.logout()

Terminal

curl -X POST "http://localhost:44388/v1/logout/"

Response

No response body.

Get the logged-in Dashboard user#

GET/v1/user/

Returns account information for the currently logged-in Formlabs Dashboard user (see /v1/login/). The response is a passthrough of the Dashboard's own account record, so it may carry fields beyond the ones documented here.

Error codes#

HTTP	`error.code`	Cause
404	`NOT_FOUND`	No Dashboard session is currently active.

ReturnsUserInfo

usernamestringRequired
Formlabs Dashboard account username or email address.
emailstring
Account email address.
idinteger
Formlabs Dashboard account id.
first_namestring
Account holder's first name.
last_namestring
Account holder's last name.

A Dashboard session is active. Returns account information for that user.

GET/v1/user/

Python

from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.get_user_info()

Terminal

curl "http://localhost:44388/v1/user/"

Response

JSON

{
  "username": "jane@example.com",
  "email": "jane@example.com",
  "id": 123456,
  "first_name": "Jane",
  "last_name": "Doe"
}