API reference

AutoAuthAPI 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: $AUTOAUTHAPI_KEY" https://autoauthapi.com/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: $AUTOAUTHAPI_KEY" https://autoauthapi.com/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: autoauth_your_key_here

• Base URL https://autoauthapi.com — HTTPS only.
• Keys start with autoauth_, so they are recognisable in a log or a secret scanner. Older keys may start with latch_; they keep working unchanged until you rotate them.
• 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: $AUTOAUTHAPI_KEY" https://autoauthapi.com/api/codes

curl -H "X-API-Key: $AUTOAUTHAPI_KEY" https://autoauthapi.com/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: $AUTOAUTHAPI_KEY" https://autoauthapi.com/api/accounts

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

curl -X POST https://autoauthapi.com/api/accounts \
  -H "X-API-Key: $AUTOAUTHAPI_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://autoauthapi.com/api/accounts \
  -H "X-API-Key: $AUTOAUTHAPI_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: $AUTOAUTHAPI_KEY" https://autoauthapi.com/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.
• 120 API requests per minute per account, counted over any 60 seconds (a sliding window), across every key the account has had: rotating the key does not start a new minute. One account's traffic never counts against another's. Past it, the request is not processed and the answer is 429:

  HTTP/1.1 429 Too Many Requests
  Retry-After: 12
  
  {"error": "rate limit exceeded", "retry_after": 12}

  Copy
  Wait retry_after seconds and send it again; refused requests are not counted, so a client that waits is let straight back in. Codes only change every period seconds, so polling faster than once a second gains nothing anyway.
• 60 failed authentications per minute per IP address (an IPv6 address counts as its whole /64 network). After that many requests with a missing or wrong X-API-Key from one address in a minute, further requests from it with a missing or wrong key get 429 instead of 401 until the minute has passed. Requests with a valid key are never affected, from that address or any other.
• The web vault has its own allowance of 600 requests per minute per account, enough for several open tabs.
• Signup and sign-in are rate limited per IP (for signup, and for password reset requests and links, an IPv6 address counts as its /64). An account that collects many failed sign-ins gives each network only a few more tries at it — an IPv4 address, or an IPv6 address's whole /64 — while a correct password from a network that has not been guessing at it still works.
• Codes are computed on demand and never stored.

Language examples

Python

import os, requests

r = requests.get("https://autoauthapi.com/api/codes",
                 headers={"X-API-Key": os.environ["AUTOAUTHAPI_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://autoauthapi.com/api/codes/1", {
  headers: { "X-API-Key": process.env.AUTOAUTHAPI_KEY },
});
if (!res.ok) throw new Error(`AutoAuthAPI ${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.AUTOAUTHAPI_KEY }}" \
      https://autoauthapi.com/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 API endpoint ever returns a stored TOTP secret. Codes come out of the API; secrets do not. There is no export route on /api/, so a leaked key cannot be used to walk off with your seeds — which is what keeps rotating that key a real remedy rather than a partial one.
• Exporting a secret is human-only, and what it hands you is the seed in plain text — QR, base32 setup key and otpauth:// URI are the same secret three ways, with nothing encrypting any of them. Treat it as a bearer credential: whoever obtains it generates valid codes for that account indefinitely, without your password, and it cannot be revoked short of re-enrolling two-factor at the site itself. That is why the path is in the browser, takes your password on the request that returns the secret, and does one entry at a time — a session cookie alone will not do it, and an API key cannot reach it at all. (Why it works this way: the reasoning is on the privacy page.)
• 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 an AutoAuthAPI code is the same code your phone's authenticator would show.