CLI Authentication

The LangCTL CLI uses API keys for authentication. API keys are SHA-256 hashed and provide secure, token-based access to your organization’s translations.

API Key Overview

What Are API Keys?

API keys authenticate CLI access without passwords:

Format: lc_ prefix + 64 hexadecimal characters
Storage: SHA-256 hashed in database
Scopes: Fine-grained permission control
Organization-level: One key per organization

lc_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

🚨

Important

Never commit API keys to git! Use environment variables or secret management systems in production.

Log in to app.langctl.com
Navigate to API Keys section
Click “Generate API Key”
Configure key:
- Name: Descriptive name (e.g., “CI/CD Production”)
- Scopes: Select permissions
Click “Generate”
Copy the key immediately (shown only once!)

[IMAGE: generate-api-key-modal.png - Screenshot showing API key generation with scopes]

Scope	Permissions
`translations:read`	View translation keys and values
`translations:write`	Create, update, delete translation keys
`translations:publish`	Publish and unpublish keys
`projects:read`	View projects
`projects:write`	Create, update, delete projects
`export`	Export translations
`import`	Import translations
`team:read`	View team members
`team:write`	Invite and manage team members

💡

Tip

Use minimum necessary scopes. For CI/CD export-only workflows, grant only translations:read and export scopes.

langctl auth login

? Enter your API key: ***************************
✓ Authenticated as: Acme Corp
✓ Configuration saved to ~/.langctlrc

langctl auth whoami

Organization: Acme Corp
User: api-key (CI/CD Production)
Scopes: translations:read, translations:write, export
Key Prefix: lc_abc123

langctl auth login --key lc_abc123...

export LANGCTL_API_KEY="lc_abc123..."
langctl auth whoami

Set via environment (recommended for CI/CD):

LANGCTL_API_KEY=lc_abc123...

- name: Export Translations
env:
  LANGCTL_API_KEY: ${{ secrets.LANGCTL_API_KEY }}
run: langctl export my-app -l en

script:
- export LANGCTL_API_KEY=$LANGCTL_API_KEY
- langctl export my-app -l en

API Key Security

Storage and Hashing

LangCTL uses industry-standard SHA-256 hashing to securely store API keys. Your keys are never stored in plain text on our servers.

ℹ️

Note

API keys are hashed using SHA-256 before storage. The plain text key is only shown once during generation and cannot be retrieved later.

Best Practices

Never expose keys:

Don’t commit to git
Don’t log in console
Don’t share via email/chat
Don’t embed in frontend code

Use environment-specific keys:

Development: lc_dev_...
Staging: lc_staging_...
Production: lc_prod_...

Rotate regularly:

Generate new keys quarterly
Revoke old keys after rotation
Update CI/CD secrets

Scope appropriately:

CI/CD Export: translations:read, export
Content Team: translations:read, translations:write
Admin Scripts: all scopes

⚠️

Warning

If an API key is compromised, revoke it immediately from the dashboard and generate a new one.

Managing API Keys

List API Keys

langctl auth keys list

API Keys:
┌──────────────────┬──────────────┬─────────────────┬────────────┐
│ Name             │ Prefix       │ Created         │ Last Used  │
├──────────────────┼──────────────┼─────────────────┼────────────┤
│ CI/CD Production │ lc_abc123    │ 30 days ago     │ 2 hours ago│
│ Development      │ lc_def456    │ 45 days ago     │ 1 week ago │
│ CLI Local        │ lc_ghi789    │ 60 days ago     │ yesterday  │
└──────────────────┴──────────────┴─────────────────┴────────────┘

From dashboard:

Go to API Keys section
Find key to revoke
Click “Revoke”
Confirm action

From CLI:

langctl auth keys revoke key-uuid

langctl auth keys revoke --prefix lc_abc123

ℹ️

Note

Revoking a key immediately invalidates it. Any CLI or API requests using that key will fail.

langctl auth keys info

Key Details:
Name: CI/CD Production
Prefix: lc_abc123
Created: March 15, 2024
Last Used: April 15, 2024 14:32 UTC
Uses: 1,247 API calls

Scopes:
✓ translations:read
✓ translations:write
✓ export

Organization:
Name: Acme Corp
ID: org-uuid
Plan: Pro

Location: ~/.langctlrc

{
"api_key": "lc_abc123...",
"organization_id": "org-uuid",
"default_project": "project-uuid",
"api_endpoint": "https://api.langctl.com"
}

Permissions: Automatically set to 600 (read/write by owner only)

Location: ./.langctlrc (current directory)

{
"project": "mobile-app-uuid",
"format": "i18next",
"output_dir": "./src/locales"
}

💡

Tip

Project config should NOT contain API keys. Use global config or environment variables for keys.

Configuration is loaded in this order (later overrides earlier):

Global config (~/.langctlrc)
Project config (./.langctlrc)
Environment variables (LANGCTL_*)
Command-line flags (--key, --org, etc.)

Error: Authentication failed: Invalid API key

Check:

echo $LANGCTL_API_KEY | head -c 10
langctl auth keys list

langctl auth logout
langctl auth login --key lc_...

Error: Permission denied: insufficient scopes

Solution: Your API key lacks required permissions. Generate new key with appropriate scopes or contact organization admin.

Error: No API key found. Run: langctl auth login

Check:

ls -la ~/.langctlrc

cat ~/.langctlrc

langctl auth login

Issue: CLI using wrong organization

Solution:

langctl org list

langctl org use org-uuid

langctl export my-app -l en --org other-org-uuid

.github/workflows/translations.yml

name: Deploy Translations

on:
push:
  branches: [main]

jobs:
export:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3

    - name: Setup Node
      uses: actions/setup-node@v3
      with:
        node-version: '18'

    - name: Install LangCTL CLI
      run: npm install -g @langctl/cli

    - name: Export Translations
      env:
        LANGCTL_API_KEY: ${{ secrets.LANGCTL_API_KEY }}
      run: |
        langctl export my-app -l en -f i18next -o ./src/locales/en.json
        langctl export my-app -l es -f i18next -o ./src/locales/es.json

.gitlab-ci.yml

export_translations:
image: node:18
before_script:
  - npm install -g @langctl/cli
script:
  - langctl export my-app -l en -f i18next -o ./locales/en.json
  - langctl export my-app -l es -f i18next -o ./locales/es.json
variables:
  LANGCTL_API_KEY: $LANGCTL_API_KEY
only:
  - main

.circleci/config.yml

version: 2.1
jobs:
export_translations:
  docker:
    - image: cimg/node:18.0
  steps:
    - checkout
    - run:
        name: Install LangCTL
        command: npm install -g @langctl/cli
    - run:
        name: Export Translations
        command: |
          langctl export my-app -l en -f i18next -o ./locales/en.json

workflows:
version: 2
build_and_deploy:
  jobs:
    - export_translations

💡

Tip

Always store API keys as CI/CD secrets, never in configuration files. Most CI/CD platforms provide secret management.

Best practice: Rotate keys every 90 days

langctl auth keys create "CI/CD Production (New)" \
--scopes translations:read,export

langctl auth login --key lc_new...
langctl export my-app -l en

langctl auth keys revoke --prefix lc_old...

#!/bin/bash

NEW_KEY=$(curl -X POST https://api.langctl.com/v1/keys \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-d '{"name":"CI/CD Production","scopes":["translations:read","export"]}' \
| jq -r '.api_key_plain')

gh secret set LANGCTL_API_KEY --body "$NEW_KEY"

curl -X DELETE https://api.langctl.com/v1/keys/$OLD_KEY_ID \
-H "Authorization: Bearer $ADMIN_TOKEN"

Next Steps

Organization Commands - Manage organizations via CLI
Project Commands - Work with projects
Export & Import - Automate translation workflows
CI/CD Integration - Set up automated pipelines