AuthCog API

Login redirect flow

AuthCog hands identity back to your site through a single-use redirect — no passwords and no provider tokens ever reach your server.

1. Generate a random, one-time browser challenge, store it in the visitor's session, and send them to central auth:

GET https://auth.authcog.com/d:my-app.com?state=BROWSER_CHALLENGE

The user signs in with any provider you enabled, then AuthCog redirects the browser back to your site with a short-lived callback hash:

GET https://my-app.com/authcog?callback=SECURE_HASH&state=BROWSER_CHALLENGE

2. Verify and consume the matching session challenge. Reject missing, mismatched or reused challenges, then exchange the hash server-side:

GET https://auth.authcog.com/d:my-app.com?user=SECURE_HASH

{ "email": "[email protected]", "name": "Ada Lovelace",
  "avatar": "https://...", "provider": "google", "realm": null, "issuer": "auth" }

The callback hash is single-use, expires 5 minutes after issue, and is bound to the exact domain it was issued for. The payload carries only profile basics — email, name, avatar and the provider used. Start your own session from it.

An exchange that fails any of those rules returns one response: 400 { "error": "unknown, expired, or already-used callback" }.

Realm trust

Configure your trusted realm host on your server and use it for both login and exchange. Use auth.authcog.com for central auth, or your-realm.authcog.com for your tenant's providers. Never select an exchange host from callback parameters.

Each exchange endpoint accepts its own realm's tokens and AuthCog's central tokens. It rejects tokens from other tenants, even when the domain and challenge match. The POST alternative, /api/tokens/verify, enforces the same trust using its request host and requires token and domain.

What you get back

The exchange returns JSON with the verified profile:

email     verified email - the primary identifier
name      display name from the provider
avatar    avatar URL (dicebear initials when the provider has no picture)
provider  informational label for how they signed in - see below
realm     realm subdomain the login belongs to, null for central auth
issuer    authenticating realm subdomain; auth for AuthCog itself

Do not validate provider, and never gate sign-in on it. A successful exchange through your configured realm host proves the issuer is trusted and the token is valid for your domain. provider is metadata for your UI ("Signed in with Google").

It is an open set of lowercase slugs and new ones appear as providers are added. Today: google, github, microsoft, email (magic link or password), pass, generic_oidc, generic_oauth2, cloudflare_access, google_iap, tailscale, generic_jwt. Treat anything unrecognized as "signed in".

Local development

For local/dev hosts (localhost, *.lvh.me, raw IPs) pass the port:

GET https://auth.authcog.com/d:my-app.lvh.me/p:8000

A port above 999 is released back over http; everything else uses https.