Your First Entry#

This page shows the credential and authentication patterns used throughout the docs. It assumes you already installed a suitable profile from Installation.

Create a Client#

Start by instantiating a Client. You can provide the API URL, Access Key ID, and Access Password in several ways:

Create a .env file in your project directory:

API_URL="https://api.labarchives.com"
ACCESS_KEYID="your_access_key"
ACCESS_PWD="your_access_password"

Then initialize the client directly:

from labapi import Client

client = Client()

Note

Automatic loading from .env requires the dotenv extra. See Installation for install profiles and package-manager commands.

Set the environment variables before running your script.

export API_URL="https://api.labarchives.com"
export ACCESS_KEYID="your_access_key"
export ACCESS_PWD="your_access_password"

$env:API_URL="https://api.labarchives.com"
$env:ACCESS_KEYID="your_access_key"
$env:ACCESS_PWD="your_access_password"

set API_URL=https://api.labarchives.com
set ACCESS_KEYID=your_access_key
set ACCESS_PWD=your_access_password

In Python:

from labapi import Client

client = Client()

You can also pass the credentials directly when creating the client:

from labapi import Client

client = Client(
    base_url="https://api.labarchives.com",
    akid="your_access_key",
    akpass="your_access_password",
)

Sign In#

To interact with the LabArchives API, you need to authenticate. The sections below cover the main workflows.

Local Interactive Authentication#

The simplest path is default_authenticate(), which lets users running on the same machine sign in through a browser.

from labapi import Client

client = Client()
user = client.default_authenticate()

Note

The local interactive path works best with labapi[dotenv,builtin-auth]. If no compatible browser is detected, labapi falls back to printing a URL so you can finish the login manually.

Tip

For server, CI, and other headless environments, see Authentication and use generate_auth_url() plus login() instead.

External App Authentication#

If you cannot use a browser on the same machine, or you want a quick manual test path, use an External App authentication code:

  1. Log in to your LabArchives account in a web browser.

  2. Click your name in the top-right corner and select External App authentication.

  3. Copy the email address and password token, then pass them to login().

from labapi import Client

client = Client()
user = client.login("your.email@example.com", "YOUR_AUTH_CODE")

Note

The External App password token is valid for only one hour.

Service and Non-Interactive Authentication#

For backend systems, scheduled jobs, and CI pipelines, do not depend on a local browser session.

Recommended flow:

  1. In your web or service layer, redirect users to client.generate_auth_url(callback_url).

  2. Capture email and auth_code from the callback request.

  3. Exchange those values via login().

  4. Store any resulting credentials or secrets using your platform’s secret manager.

For implementation details and operational guidance, see the full Authentication guide.

Get a Notebook#

Once you have a User object, you can access notebooks by name or iterate over them:

notebook = user.notebooks["My Notebook"]

for notebook_name in user.notebooks:
    print(notebook_name)

for notebook in user.notebooks.values():
    print(notebook.name, notebook.id)

Write Entries#

After you have a notebook, navigate to a page and create entries:

Tip

Choose the entry type based on what LabArchives should render:

from labapi import HeaderEntry, PlainTextEntry, TextEntry

page = notebook.traverse("Experiments/Project A/Results")

page.entries.create(TextEntry, "<p><strong>Trial 1:</strong> Successfully ran.</p>")
page.entries.create(PlainTextEntry, "<strong>Raw instrument log line</strong>")
page.entries.create(HeaderEntry, "Follow-up Measurements")