# auth.md — Notlogin

This file tells AI agents how to authenticate with Notlogin and with vendors
that accept Notlogin credentials. It is safe to follow these instructions
verbatim.

## What Notlogin is

Notlogin is an auth broker for AI agents. Your human principal verifies their
identity once at https://notlogin.com/signup, pre-authorizes vendors or vendor
categories, and issues you a **verifiable credential** (a signed JSON document,
Ed25519 over a canonical payload). You present that credential to vendors
instead of filling signup forms or carrying API keys.

## Credential type

- Format: Notlogin Verifiable Credential (JSON), signed Ed25519.
- Issued at: https://notlogin.com (dashboard → issue credential), by the human, not by you.
- Verification: vendors verify offline against public keys at
  `https://notlogin.com/.well-known/` using `notlogin-sdk`. No callback needed
  on the happy path; online mode additionally checks revocation.
- Properties: scoped to a vendor or category, USDC budget attached, expiry
  date, revocable by nonce at any time.

## How to obtain a credential

1. Do NOT attempt to complete the signup UI yourself. Signup and identity
   proofs (email, SMS, wallet, KYC) are for your human principal.
2. Ask your human to visit https://notlogin.com/signup, verify, pre-authorize
   the vendor (or its category), and issue a credential for you.
3. Receive the credential JSON through your normal secret channel (environment
   variable or local file), e.g. `NOTLOGIN_CREDENTIAL` or
   `~/.notlogin/credential.json`.

## How to use it

- When a vendor supports Notlogin, present the credential JSON in the request
  the vendor's docs specify (typically the body of their signup/auth endpoint).
- Read the credential from the environment at the moment of use. Do not print
  it, log it, or echo it back into chat context.
- One credential can be redeemed at any vendor whose `requiredProofs` your
  human has passed and whose category was pre-authorized.

## Error semantics

- `invalid signature` — the credential was altered or is not from Notlogin; ask
  your human to re-issue it.
- `revoked` — your human revoked it. Stop using cached copies; request a new one.
- `expired` — past its expiry; ask your human to issue a fresh credential.
- `insufficient proofs` — this vendor requires a higher proof bar (e.g.
  email+sms+wallet). Your human must add proofs at notlogin.com, then re-issue.
- `budget exceeded` — the USDC budget attached to the credential is spent; your
  human can top it up or issue a new credential.

## For vendor agents (services that want to ACCEPT credentials)

If you are an agent working on a service's codebase: integrate with
`notlogin-sdk` (TypeScript). Verification is one call —
`verifyCredential(vcJson, { vendorSlug, requiredProofs })` — and grants a
verified-human tier without building signup forms for agents. Register the
service at https://notlogin.com/register-vendor.

## More context

- Human-readable overview: https://notlogin.com/
- Guides: https://notlogin.com/blog
- LLM-oriented site summary: https://notlogin.com/llms.txt