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.

Obtain API Keys#

Every request to the LabArchives API is signed with an Access Key ID (akid) and Access Password issued by LabArchives. These identify your application; the sign-in flows further down this page additionally authenticate individual users. There is no self-service portal for API keys — they are issued on request:

  • If your institution has a LabArchives enterprise license, ask your institution’s LabArchives site administrator (or your LabArchives Enterprise Success Team contact) to request API access. Provide the name and email address for each existing LabArchives account that needs API access.

  • Otherwise, contact LabArchives support at support@labarchives.com.

When issuing the keys, LabArchives will confirm the API base URL for your region (for example, https://api.labarchives.com for US-hosted accounts — the default used throughout these docs).

Treat the Access Password like any other secret: keep it out of version control and supply it via a .env file or environment variables as shown below.

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#

Local Interactive Authentication#

For local interactive use, call default_authenticate(), which lets users running on the same machine sign in through a browser.

from labapi import Client

with Client() as client:
    user = client.default_authenticate()

Note

Use labapi[dotenv,builtin-auth] for .env loading and automatic browser launch. If automatic browser launch is unavailable, 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 for a manual login test, 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 the complete flow, see Authentication.

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. Choose the entry class by the output you want in LabArchives:

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")