Skip to content

Authentication💡

The 3Di API uses access tokens to authenticate users. They need to be included as an HTTP authentication header with all requests sent to the 3Di API.

Expiry token

Access tokens are only valid for one day. The "refresh" token can be used to get a new access token via the /auth/refresh-token/ endpoint. The refresh token has a lifetime of 2 days.

Token💡

Create💡

Get an access and refresh token. The access token needs to be sent as an HTTP authentication header with every request, prefixed with 'Bearer ' (case-sensitive).

POST /auth/token/

Parameter type Description
username string your username, case sensitive
password string your password, case sensitive
curl --header "Content-Type: application/json" \
     --request POST \
     --data \
       '{"username":"<your username goes here>",
         "password":"<your password goes here>"}' \
     https://api.3di.live/v3/auth/token/

Example passing the access token in an HTTP authentication header:

curl  --request GET \
      --header "Authorization: Bearer <your token here>  \
      --header  "accept: application/json" \
      "https://api.3di.live/v3/simulations/"

The refresh token can be used to get a new access token via the /auth/refresh-token/ endpoint.

Refresh💡

Create💡

POST /auth/refresh-token/

Parameter type Description
refresh string token gained by the initial auth/token request
curl --header "Content-Type: application/json"  \
     --request POST \
     --data \
       '{"refresh":"<token gained by the initial `auth/token` request>"}' \
     https://api.3di.live/v3/auth/refresh-token/

Using the ThreediApi💡

When using the ThreediApi three settings need to be in place to make requests to the 3Di API

  • the host name
  • the username to login with and
  • the user's password

These settings should be stored in environment variables, or in a .env file.

# A sample .env file could look like this
THREEDI_API_HOST=https://api.3di.live
THREEDI_API_USERNAME=black.sheep
THREEDI_API_PASSWORD=myverysecretmehhh

The file path can then be passed to the ThreediApi on initialisation.

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

env_file = "<path>/.env"
api_client: V3Api = ThreediApi(env_file)

# Get list of simulations
api_client.simulations_list()

# or as context manager
with ThreediApi(env_file) as api_client:
    api_client: V3Api
    api_client.simulation_list()

Alternatively, you can create a config dictionary and pass that to the ThreediApi

from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

THREEDI_API_HOST = https://api.3di.live
THREEDI_API_USERNAME = "black.sheep"
THREEDI_API_PASSWORD = "myverysecretmehhh"

config = {
    "THREEDI_API_HOST": API_HOST,
    "THREEDI_API_USERNAME": USERNAME,
    "THREEDI_API_PASSWORD": PASSWORD
}

api_client: V3Api = ThreediApi(config=config)

# Get list of simulations
api_client.simulation_list()