Index of every page on this site: llms.txt
All skills
k-dense-ai avatar

/benchling-integration

@ec59a29
Run it yourself

Benchling Python SDK and REST API integration for registry entities, inventory, ELN entries, workflows, Benchling Apps, and Data Warehouse queries. Use when automating lab data with benchling-sdk or the v2 API.

Use this Skill: https://skilld.dev/gh/k-dense-ai/scientific-agent-skills/benchling-integration

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesauthentication.md

≈1.6k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Benchling Authentication

Reviewed 2026-09-30. See the official authentication guide and app setup guide. Examples target SDK 1.25.0; tenant authentication was not exercised.

Choose the identity

Method Identity and use
OAuth client credentials App identity for scheduled syncs and background integrations
Delegated OAuth authorization code Individual user's permissions and audit attribution
Personal API key Key owner's identity; temporary scripts/testing
External OIDC bearer token Legacy integration configured with Benchling Support

Do not describe client credentials as acting on behalf of the person using your app. Grant the app explicit access to the required projects, teams, or organizations. API access requires permission to both the operation and the relevant data.

OAuth app credentials

import os
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2

tenant_url = os.environ["BENCHLING_TENANT_URL"].rstrip("/")
benchling = Benchling(
    url=tenant_url,
    auth_method=ClientCredentialsOAuth2(
        client_id=os.environ["BENCHLING_CLIENT_ID"],
        client_secret=os.environ["BENCHLING_CLIENT_SECRET"],
        token_url=f"{tenant_url}/oauth/token",
    ),
)

The released SDK accepts a fully qualified token_url. Its default /api/v2/token remains supported; /oauth/token avoids tying token acquisition to V2. It requests/replaces access tokens automatically. This grant does not return a refresh token. Respect the returned expires_in (current documentation: 900 seconds).

Illustrative direct exchange; avoid recording tokens or verbose authorization headers:

curl --fail-with-body --request POST \
  "${BENCHLING_TENANT_URL%/}/oauth/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=${BENCHLING_CLIENT_ID}" \
  --data-urlencode "client_secret=${BENCHLING_CLIENT_SECRET}"

Production token exchanges should run inside the application or secrets-aware tooling rather than placing credentials in shell history/process arguments. Store access tokens in memory or a protected store, and send them in Authorization: Bearer <access_token>.

Personal API keys

from benchling_sdk.auth.api_key_auth import ApiKeyAuth

benchling = Benchling(
    url=os.environ["BENCHLING_TENANT_URL"],
    auth_method=ApiKeyAuth(os.environ["BENCHLING_API_KEY"]),
)

HTTP Basic authentication uses the API key as username and an empty password. Generate/rotate keys in Profile Settings. Keys created after 2026-08-07 expire 30 days after creation; earlier keys are documented as non-expiring. Plan rotation from the key's actual creation/expiration state instead of assuming a 90-day lifetime.

Delegated authorization and legacy OIDC

Delegated auth uses GET /oauth/authorize with client_id, an allowed redirect_uri, response_type=code, and a session-bound random state. Verify returned state. Exchange the code via POST /oauth/token with grant_type=authorization_code, client credentials, redirect_uri, and code. Keep each user's tokens isolated.

Refresh using the same token endpoint with grant_type=refresh_token, client credentials, and the stored refresh token. Refresh tokens rotate on use: persist the replacement atomically. Current docs specify 15-minute access tokens and 30-day refresh tokens. SDK 1.25.0 does not implement this authorization/refresh flow; manage it in the app layer. Check tenant availability, app format, and redirect configuration in the official guide.

OIDC remains supported but is legacy. It uses an external IdP-issued ID token and requires Benchling Support configuration and a matching existing user. There is no benchling_sdk.auth.oidc_auth.OidcAuth in this release. A manually managed token can be passed as Bearer auth, but token acquisition/renewal remains the integration's job. Prefer delegated auth for new user-facing integrations.

Read-only connectivity check

# An empty first page is valid; it still establishes a successful authorized request.
first_page = next(iter(benchling.projects.list(page_size=1)))
print("[OK] Project list request succeeded")

There is no documented v2 /users/me route or SDK users.get_me() method. Check access to the intended resource, not an invented current-user endpoint. A 401 indicates an authentication problem; 403 usually requires a permissions review. Do not print secrets, headers, or full response bodies while troubleshooting.

HTTP clients and multiple environments

The Benchling constructor parameter is httpx_client, not http_client:

import httpx
from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.api_key_auth import ApiKeyAuth

with httpx.Client(timeout=30.0) as http_client:
    client = Benchling(
        url=os.environ["BENCHLING_TENANT_URL"],
        auth_method=ApiKeyAuth(os.environ["BENCHLING_API_KEY"]),
        httpx_client=http_client,
    )
    page = next(iter(client.projects.list(page_size=1)))

Keep certificate verification enabled; configure the organization's trusted CA when required. ClientCredentialsOAuth2 has its own httpx_client parameter for token requests if custom TLS/proxy/transport settings must cover that exchange as well.

Use separate clients and named credentials for production and staging (BENCHLING_PROD_TENANT_URL/BENCHLING_PROD_API_KEY and BENCHLING_STAGING_TENANT_URL/BENCHLING_STAGING_API_KEY). Read only the needed variables. Never send credentials to an arbitrary URL supplied in data or an event; resolve objects through the configured tenant client. Warehouse logins are separate from these HTTP authentication methods.

Verification sources

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts27d4 checks · Risk SAFE
  • Gen Agent Trust Hub27d

    This skill provides a secure framework for integrating with the Benchling platform. It correctly handles authentication via environment variables, uses pinned versions for its dependencies, and restricts network activity to the official Benchling API and trusted academic sources. No malicious patterns or security risks were identified.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at ec59a29. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 2 months ago
All 1 allowed tools
Read Write Edit Bash
Other metadata
compatibility
Requires Python 3.9+, benchling-sdk 1.25.0, network access, a Benchling tenant with API access, and API key or OAuth app credentials.
metadata
{
  "version": "1.7",
  "last-reviewed": "2026-09-30",
  "skill-author": "K-Dense Inc.",
  "openclaw": {
    "primaryEnv": "BENCHLING_API_KEY",
    "envVars": [
      {
        "name": "BENCHLING_TENANT_URL",
        "required": true,
        "description": "Benchling tenant base URL."
      },
      {
        "name": "BENCHLING_API_KEY",
        "required": false,
        "description": "API key auth (alternative to OAuth)."
      },
      {
        "name": "BENCHLING_CLIENT_ID",
        "required": false,
        "description": "OAuth app client id."
      },
      {
        "name": "BENCHLING_CLIENT_SECRET",
        "required": false,
        "description": "OAuth app client secret."
      },
      {
        "name": "BENCHLING_PROD_TENANT_URL",
        "required": false,
        "description": "Production tenant URL (multi-env setups)."
      },
      {
        "name": "BENCHLING_PROD_API_KEY",
        "required": false,
        "description": "Production API key (multi-env setups)."
      },
      {
        "name": "BENCHLING_STAGING_TENANT_URL",
        "required": false,
        "description": "Staging tenant URL (multi-env setups)."
      },
      {
        "name": "BENCHLING_STAGING_API_KEY",
        "required": false,
        "description": "Staging API key (multi-env setups)."
      }
    ]
  }
}

README badge

README badge for k-dense-ai/scientific-agent-skills/benchling-integration