Authentication

Labelty supports browser sessions (for the web app) and project API keys (for SDK, cURL, CI, and workflow run calls).

This page focuses on project API keys, because that is what automation and the Python SDK use.

What a project API key is

• The secret starts with lty_
• It belongs to exactly one project
• The project is resolved from the key — you do not need a separate LABELTY_PROJECT_ID for the SDK
• You send it as: Authorization: Bearer lty_…

Keep the secret private

Treat the key like a password. Do not commit it to git. Prefer environment variables or a secret manager.

Who can create a key

Creating and managing keys requires the appropriate organization permission (commonly described as API key manage / org.api_keys.manage in the product). Typical roles that can use ML automation include ML Engineer and Project Manager.

Missing information

Exact role ↔ permission matrices for every plan can change. If create fails with 403, ask an org admin to grant API key access for your role. See Open questions.

Create a key in the UI

1. Sign in to the Labelty web app.
2. Open your project.
3. In the project navigation, open API Key
   (route shape: /dashboard/project/{id}/api-key).
4. Create a new key:
   • Give it a clear name (for example ci-training or local-dev).
   • Choose an expiry if offered (never / 30 days / 1 year — options depend on the UI).
5. Copy the secret immediately. Labelty shows the full lty_… value at create time; you typically cannot read it again later.
6. Store it somewhere safe (password manager, CI secret store, or a local .env that is gitignored).

Screenshot: Project → API Key → Create key dialog (copy secret once)

Store the key locally

Create a .env file outside version control (or export variables in your shell):

# Example — do not commit real values
export LABELTY_API_URL="https://api.development.labelty.ai/api/v1"
export LABELTY_API_KEY="lty_your_secret_here"

On Windows PowerShell:

$env:LABELTY_API_URL = "https://api.development.labelty.ai/api/v1"
$env:LABELTY_API_KEY = "lty_your_secret_here"

Why /api/v1 is part of the URL

The SDK and HTTP examples expect the API root including the version prefix. Passing only the host without /api/v1 will produce 404s.

Use the key with HTTP

curl -s "https://api.development.labelty.ai/api/v1/projects/current" \
  -H "Authorization: Bearer $LABELTY_API_KEY" \
  -H "Content-Type: application/json"

What this does: asks Labelty which project this key belongs to.

Why it is useful: confirms the key works before you write Python or deploy a workflow.

Expected output: a JSON envelope with data.id, data.name, and other project fields.

Common errors:

Symptom	Likely cause
401	Missing/wrong key, or key revoked
403	Key valid but action not allowed for this key / plan
Empty / connection error	Wrong host, VPN, or TLS issues

Use the key with the SDK

The client does not auto-read environment variables. Pass them explicitly:

import os
from labelty_sdk import LabeltyClient

with LabeltyClient(
    api_url=os.environ["LABELTY_API_URL"],
    api_key=os.environ["LABELTY_API_KEY"],
) as client:
    project = client.project
    print(project.id, project.name)

API-key mutation allowlist

Project API keys can call many GET endpoints. Write operations are restricted to an allowlist (for example training runs, workflow run, some model operations). If a write returns 403 while a session user can do it in the UI, the endpoint may not be allowlisted for keys yet.

Next step

Install the SDK: Install and connect.