Skip to content

Authentication

Learn how to authenticate your API requests to Laminr.

API Keys

Laminr uses API keys to authenticate requests. API keys belong to service accounts, so be sure to keep them secure!

Keys look like lam_ followed by a random string (some keys also embed a tenant code, e.g. lam_acme_…). The lam_ prefix is required — requests whose x-api-key value doesn't start with it are not treated as API-key requests at all.

Creating a Service Account and API Key

Tenant Admin Required

You must be a tenant administrator to create service accounts and API keys. If you don't have admin access — or you don't see the Service Accounts section at all (it is enabled per organization) — contact your organization's Laminr administrator or support@laminr.ai.

Step 1: Navigate to Service Accounts

  1. Log in to your Laminr dashboard
  2. Click on your profile menu in the top navigation
  3. Select Tenant Settings from the dropdown
  4. Navigate to the Service Accounts section in the left sidebar

Step 2: Create a Service Account

  1. Click Create Service Account
  2. Give your service account a descriptive name (e.g., "Production API", "CI/CD Pipeline")
  3. Click Create to save the service account

Step 3: Create an API Key

  1. Open your newly created service account
  2. Click Create API Key
  3. Copy the key immediately - you won't be able to see it again!

Service Account Organization

You can create multiple service accounts for different purposes (e.g., one for production, one for development). Each service account can have multiple API keys, making it easy to rotate keys or separate access by environment.

Save Your API Key

The API key is only displayed once when created. Make sure to copy and store it securely before closing the dialog. If you lose it, delete the key and create a new one.

Using Your API Key

Include your API key in the x-api-key header of every request:

x-api-key: YOUR_API_KEY

Example request:

curl https://api.laminr.ai/api/v2/packages \
  -H "x-api-key: ${LAMINR_API_KEY}"

Key Scopes

An API key can optionally be restricted to scopes. A key with no scopes has full access; a scoped key can only call endpoints guarded by one of its scopes. Scopes come in a read-only / admin pair per functional domain — read-only covers safe methods (GET), admin covers mutating methods (POST/PATCH/DELETE):

Domain Read scope Admin scope
Loan packages (files, transactions, results, …) LOAN_PACKAGE_READ_ONLY LOAN_PACKAGE_ADMIN
Eligibility models (rules, overlays, …) ELIGIBILITY_MODEL_READ_ONLY ELIGIBILITY_MODEL_ADMIN
Users and identity (profiles, members, invites, …) USER_READ_ONLY USER_ADMIN
Tenant administration (settings, roles, workgroups, …) TENANT_READ_ONLY TENANT_ADMIN

For the package/file workflows in these guides, a key needs LOAN_PACKAGE_ADMIN to create packages and attach files, or LOAN_PACKAGE_READ_ONLY for read-only integrations. A scoped key calling an endpoint outside its scopes receives a 403 (see below).

Security Best Practices

Keep Your Keys Secret

Never Expose Your API Key

  • Don't commit API keys to version control
  • Don't include them in client-side code
  • Don't share them in support tickets or public forums
  • Use environment variables to store them

Environment Variables

Store your API key in environment variables:

Bash/Linux/macOS:

export LAMINR_API_KEY="lam_abc123xyz789..."

Python:

import os

api_key = os.environ.get("LAMINR_API_KEY")

Node.js:

const apiKey = process.env.LAMINR_API_KEY;

Rotate Keys Regularly

If you suspect a key has been compromised:

  1. Create a new API key on the service account in your dashboard
  2. Update your application with the new key
  3. Delete the old key immediately

Use Different Keys for Different Environments

Create separate API keys (or service accounts) for:

  • Development: For local development and testing
  • Staging: For your staging environment
  • Production: For your production environment

This allows you to isolate issues, track usage by environment, and revoke keys without affecting other environments.

Authentication Errors

401 Unauthorized

An invalid, revoked, or expired key returns the standard Laminr error envelope:

{
  "code": 401,
  "error": "ApiKeyInvalidError",
  "message": "Invalid or expired API key",
  "detail": "Invalid or expired API key"
}

A valid key whose service account has been deactivated returns the same envelope with a different error:

{
  "code": 401,
  "error": "ApiKeyInactiveServiceAccountError",
  "message": "Service account is inactive",
  "detail": "Service account is inactive"
}

A missing x-api-key header — or a value without the lam_ prefix — isn't recognized as an API-key request, so the request falls through to the other authentication methods and typically fails with a 401 asking for credentials.

403 Forbidden

A valid key that lacks permission for the endpoint returns:

{
  "detail": "You do not have permission to perform this action."
}

Common causes:

  • The key is scoped and the endpoint requires a scope it doesn't hold (e.g. a LOAN_PACKAGE_READ_ONLY key calling a mutating endpoint that requires LOAN_PACKAGE_ADMIN)
  • The resource belongs to a different tenant

Next Steps