API reference

Latch stores your two-factor accounts and hands the live TOTP codes back over HTTP. One header, five endpoints, JSON in and JSON out. Every example on this page runs as-is once your key is in place.

Quickstart

Three steps, about a minute.

• 1. Get a key. Create a free account. Your personal API key is minted at signup and shown in your vault under Your API.
• 2. Store a 2FA secret. Drop a screenshot of the setup QR code into the vault, paste the “can’t scan?” setup key, or POST it (see Add an account).
• 3. Read the code from anything that speaks HTTP.

curl -H "X-API-Key: $LATCH_API_KEY" https://latch.cc/api/codes

{
  "codes": [
    {
      "id": 1,
      "issuer": "GitHub",
      "label": "ci-bot@example.com",
      "code": "130604",
      "seconds_remaining": 22,
      "digits": 6,
      "period": 30,
      "algorithm": "SHA1"
    }
  ]
}

seconds_remaining is how long this code stays valid. When it is low, wait the window out instead of submitting a code that expires mid-request:

#!/bin/sh
# print a code with a full window ahead of it
while :; do
  json=$(curl -sf -H "X-API-Key: $LATCH_API_KEY" https://latch.cc/api/codes/1)
  left=$(printf '%s' "$json" | jq -r .seconds_remaining)
  [ "$left" -ge 5 ] && printf '%s\n' "$json" | jq -r .code && break
  sleep "$left"
done

Authentication

Send your key in the X-API-Key header on every request. No OAuth dance, no token exchange, no expiry.

X-API-Key: latch_your_key_here

• Base URL https://latch.cc — HTTPS only.
• Keys start with latch_, so they are recognisable in a log or a secret scanner.
• Missing, malformed or unknown key → 401.
• A key is scoped to exactly one vault. It can never read another account's codes: an id belonging to someone else returns 404, identical to an id that does not exist.
• Rotate a key any time from Your API in the vault. The old key stops working immediately.

Reading codes

curl -H "X-API-Key: $LATCH_API_KEY" https://latch.cc/api/codes

curl -H "X-API-Key: $LATCH_API_KEY" https://latch.cc/api/codes/1

{
  "id": 1,
  "issuer": "GitHub",
  "label": "ci-bot@example.com",
  "code": "130604",
  "seconds_remaining": 22,
  "digits": 6,
  "period": 30,
  "algorithm": "SHA1"
}

Managing accounts

curl -H "X-API-Key: $LATCH_API_KEY" https://latch.cc/api/accounts

{
  "accounts": [
    {"id": 1, "issuer": "GitHub", "label": "ci-bot@example.com",
     "digits": 6, "period": 30, "algorithm": "SHA1"}
  ]
}

curl -X POST https://latch.cc/api/accounts \
  -H "X-API-Key: $LATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secret":"JBSWY3DPEHPK3PXP","issuer":"GitHub","label":"ci-bot@example.com"}'

# same thing, straight from the otpauth:// URI the setup QR encodes
curl -X POST https://latch.cc/api/accounts \
  -H "X-API-Key: $LATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uri":"otpauth://totp/GitHub:ci-bot@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub"}'

curl -X DELETE -H "X-API-Key: $LATCH_API_KEY" https://latch.cc/api/accounts/1

Errors

Every error is JSON with a single error string at the matching HTTP status. Nothing under /api/ ever returns an HTML page.

{"error": "invalid or missing API key"}

Limits

• A free account holds up to 50 authenticator entries. Adding past that returns 403.
• No read rate limit — but codes only change every period seconds, so polling faster gains nothing.
• Signup and sign-in are rate limited per IP.
• Codes are computed on demand and never stored.

Language examples

Python

import os, requests

r = requests.get("https://latch.cc/api/codes",
                 headers={"X-API-Key": os.environ["LATCH_API_KEY"]},
                 timeout=15)
r.raise_for_status()
for c in r.json()["codes"]:
    print(c["issuer"], c["code"], c["seconds_remaining"], "s left")

Node

const res = await fetch("https://latch.cc/api/codes/1", {
  headers: { "X-API-Key": process.env.LATCH_API_KEY },
});
if (!res.ok) throw new Error(`latch ${res.status}: ${await res.text()}`);
const { code, seconds_remaining } = await res.json();
if (seconds_remaining < 5) await new Promise(r => setTimeout(r, seconds_remaining * 1000));
console.log(code);

GitHub Actions

- name: Fetch a 2FA code
  id: totp
  run: |
    code=$(curl -sf -H "X-API-Key: ${{ secrets.LATCH_API_KEY }}" \
      https://latch.cc/api/codes/1 | jq -r .code)
    echo "::add-mask::$code"
    echo "code=$code" >> "$GITHUB_OUTPUT"

Security, honestly

• Secrets are encrypted at rest with Fernet (AES-128-CBC + HMAC-SHA256). The encryption key lives outside the database.
• No endpoint ever returns a stored TOTP secret — not even to the account that owns it. Codes come out; secrets do not.
• API keys are stored as a SHA-256 hash for lookup, and every vault is scoped to its owner in the query itself.
• Keep the key in a secrets manager or CI secret, never in a repo, and mask it in build logs.
• Rotate from Your API in the vault the moment a key touches a shared machine.
• Keep a second 2FA method — recovery codes or a hardware key — on anything you cannot afford to be locked out of.

Codes are generated by a TOTP implementation written against RFC 6238 using only the Python standard library and checked against the RFC's own test vectors, so a Latch code is the same code your phone's authenticator would show.