LabArchives Authentication and Regions

Verified against official public sources on 2026-07-23. LabArchives may provide additional institution-specific development documentation with API credentials; that documentation controls when it differs from this summary.

Access prerequisites

ELN

The official ELN subscription guide (updated 2025-09-24) lists developer API access as an Enterprise capability. An Access Key ID and Access Password are issued by LabArchives for a specific organization/vendor and intended purpose. They are not ordinary account credentials.

Official source: https://help.labarchives.com/hc/en-us/articles/11723701830676-ELN-for-Research-Introduction-and-Subscription-Plans

Inventory API v1

The Inventory FAQ (updated 2026-05-19) states that API access is available only to Enterprise and Enterprise Plus licensees. The caller must:

• have a LabArchives account,
• have an Inventory account,
• be given API access, and
• remain subject to Inventory application access rights.

An eligible Inventory license member can request access through [email protected].

Official source: https://help.labarchives.com/hc/en-us/articles/11811035048212-Inventory-FAQs

Credential types

Keep these values distinct:

• Access Key ID (akid) — identifies the API client.
• Access Password — secret HMAC-SHA-512 key; it is never sent as an API parameter or request-body field.
• UID — user ID scoped to the Access Key ID that obtained it. It is persistent until revoked, but it is not portable across API keys.
• Authorization code — short-lived value returned by the API user-login flow and redeemed promptly through users::user_access_info.
• Temporary password token — user-generated alternative accepted as the password parameter by users::user_access_info.
• Inventory Lab ID — identifies the current Inventory lab and is documented as X-LabArchives-LabId.

Do not use a normal LabArchives account password in API scripts.

Regional browser and ELN API hosts

The two host types are intentionally shown in separate columns. Login URLs come from the help-center SSO article updated 2025-11-04; API URLs come from the official ELN API overview updated 2025-11-03.

Official sources:

• https://help.labarchives.com/hc/en-us/articles/11728160845332-Using-an-Institutional-Single-Sign-on-for-LabArchives-Access
• https://mynotebook.labarchives.com/share/LabArchives%20API/NS4yfDI3LzQvVHJlZU5vZGUvMTF8MTMuMg

The official ELN overview recommends utilities::api_base_urls for distributed applications so they can discover future regional API additions. The bundled validator intentionally pins the five hosts documented at this refresh date.

Inventory absolute base URLs

The public Inventory authentication and endpoint pages reviewed here document relative /public/v1/... paths and required headers. They did not establish a complete regional absolute API base-URL table. Inventory browser hosts are not proof of API hosts. Use the base URL supplied with the institution/vendor API documentation; do not derive one from a login URL.

Named environment variables

These names are conventions used by this skill's local helpers:

LABARCHIVES_ELN_API_URL
LABARCHIVES_ACCESS_KEY_ID
LABARCHIVES_ACCESS_PASSWORD
LABARCHIVES_USER_ID
LABARCHIVES_INVENTORY_LAB_ID

Use a shell session, OS keychain, workload secret store, or institution-approved secret manager to populate them. The scripts:

• inspect only these exact names,
• never walk parent directories for .env,
• never write secret files, and
• never print credential values.

Validate presence and endpoint selection:

uv run scripts/setup_config.py check
uv run scripts/setup_config.py check \
  --require-user-id --require-inventory-lab-id

--prompt-missing-secret uses getpass for a missing Access Password and keeps the value in memory only. It does not save or authenticate it.

ELN API user authorization

The official page describes an OAuth-like redirect flow. It does not document generic OAuth 2.0 client credentials, /oauth/authorize, or /oauth/token endpoints.

1. Select the user's correct regional API host.
2. Redirect the user to the host's /api_user_login path with akid, expires, sig, and redirect_uri.
3. For this special signature, use the exact unencoded redirect URI in place of the normal API method name.
4. LabArchives performs account/SSO login and redirects back with auth_code and email.
5. Promptly call the documented users::user_access_info, passing the authorization code as its password parameter and the returned email.
6. Store the resulting UID only in approved secure state. It remains bound to the Access Key ID and can be revoked.

If redirects cannot be used, the official flow allows a user-generated temporary password token in the same password parameter. Handle it with getpass or a secure UI field; never put it on a command line or in a log.

Official user-login page (updated 2023-03-03): https://mynotebook.labarchives.com/share/LabArchives%20API/ODEuOXwyNy82My05My9UcmVlTm9kZS8yMjYyMTU0MTg3fDIwNy44OTk5OTk5OTk5OTk5OA==

Request signing

The official call-authentication page (updated 2023-05-10) defines:

message = AccessKeyID + api_method_input + expires
signature = Base64(HMAC-SHA-512(key=AccessPassword, message=message))

There are no separators. expires is current epoch milliseconds, corrected for server clock skew when needed—not a future token lifetime. The official page allows two minutes for latency/minor clock synchronization, while the best-practices page recommends utilities::epoch_time for unreliable clocks.

• ELN ordinary call: api_method_input is the method name only, without its class.
• ELN user-login redirect: it is the unencoded redirect URI.
• Inventory v1: it is the exact relative route, including resolved path parameters and excluding the query string.

Official signing page: https://mynotebook.labarchives.com/share/LabArchives%20API/Ny44fDI3LzYvVHJlZU5vZGUvMTE1MzU5MTAyNXwxOS44

Use scripts/entry_operations.py self-test to check the implementation against the official published test vector without credentials or network access.

TLS and secret handling

• Permit only https.
• Never disable certificate or hostname validation.
• If an institutional interception proxy is required, use its approved CA bundle and keep hostname verification enabled.
• Reject credentials embedded in URLs and reject redirects to unapproved hosts.
• Do not log full ELN URLs after signing; authentication appears in the query.
• Do not log Inventory authentication headers.
• Do not include the Access Password in query parameters, headers, form data, or JSON. It is an HMAC key only.
• Rotate/revoke credentials through LabArchives after suspected exposure.

Troubleshooting checklist

1. Confirm API access is enabled for the exact product and account.
2. Confirm the browser account and API host belong to the same region.
3. Confirm the UID was obtained with the same Access Key ID now in use.
4. Confirm the local clock or epoch_time adjustment.
5. Confirm the signing input: method-only for ELN, exact relative route for Inventory, unencoded redirect URI for user login.
6. Confirm URL encoding is applied only after Base64 for the ELN sig.
7. Confirm Inventory path parameters are resolved and query parameters excluded from its signature.
8. Report status, official API error code, and a redacted response to support. Never include signatures, authorization codes, tokens, or passwords.