V2: Agent authentication

API-first sign-up and sign-in for tools, CLIs, and automation without using the browser OAuth flow.

Use this page when a script or agent must obtain a CodeFundi API key and (when required) complete email OTP verification.

Discover routes first: API reference and V2 overview.

Prerequisites

Base URL (production): https://api.codefundi.app. Append paths such as /v2/auth/authenticate.
TLS: Password mode requires HTTPS in production; send the password only in the header documented below (never in the JSON body).

Flow overview

New accounts (OTP)

POST /v2/auth/authenticate with auth_mode: "otp" and should_create_user: true. Sends a 6-digit code to the email. Response may include api_key with key_state: "agent_pending" until verification.
POST /v2/auth/verify with email + token (the code). Returns a session and sets the key to key_state: "active" when verification succeeds.
Call other V2 routes with header X-API-Key set to the UUID string in data.api_key.key (see V2: API keys for rotation and listing).

Returning accounts (OTP)

POST /v2/auth/authenticate with auth_mode: "otp" and should_create_user: false. Sends a new code.
POST /v2/auth/verify. Same as above.

POST /v2/auth/authenticate with auth_mode: "password", should_create_user true (register) or false (login), JSON email (and optional profile data), and header X-CodeFundi-Auth-Password (minimum length enforced by the API).
If the project returns a session immediately (e.g. email confirmation disabled), you can skip /v2/auth/verify and use X-API-Key from the response when key_state is active.

Resend email / OTP

POST /v2/auth/resend with email and optional type (signup, email_change, email). Subject to rate limits.

Step 1: Authenticate (OTP, new user)

POST https://api.codefundi.app/v2/auth/authenticate

Summary: Start email OTP; creates the auth user when should_create_user is true. No X-API-Key on this route.

Request body (high level)

Field	Required	Description
`auth_mode`	yes	`otp` or `password` (alias: `mode`).
`email`	yes	Valid email address.
`should_create_user`	no	`true` first time, `false` for returning users (default false).

Responses: 200 with status: "ok" and data; 400, 429 (see Retry-After), 503 when the auth service is temporarily unavailable.

cURL

auth-authenticate-otp.sh


curl -sS -X POST "https://api.codefundi.app/v2/auth/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_mode": "otp",
    "email": "agent@example.com",
    "should_create_user": true
  }'

JavaScript

auth-authenticate-otp.ts


const  = await ('https://api.codefundi.app/v2/auth/authenticate', {
  : 'POST',
  : { 'Content-Type': 'application/json' },
  : .({
    : 'otp',
    : 'agent@example.com',
    : true,
  }),
})
const 
const json: anyjson = await .()

Python

auth_authenticate_otp.py


import json
import urllib.request
 
body = {
    "auth_mode": "otp",
    "email": "agent@example.com",
    "should_create_user": True,
}
req = urllib.request.Request(
    "https://api.codefundi.app/v2/auth/authenticate",
    data=json.dumps(body).encode(),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req) as resp:
    print(resp.read().decode())

Typical data fields in the response include user_id, email, session (often null until verify), verification_required, and api_key with key and key_state (agent_pending | active).

Step 1: Authenticate (password, new user)

POST https://api.codefundi.app/v2/auth/authenticate with X-CodeFundi-Auth-Password (or X-Auth-Password).

cURL

auth-authenticate-password.sh


curl -sS -X POST "https://api.codefundi.app/v2/auth/authenticate" \
  -H "Content-Type: application/json" \
  -H "X-CodeFundi-Auth-Password: ${CODEFUNDI_TEMP_PASSWORD}" \
  -d '{
    "auth_mode": "password",
    "email": "agent@example.com",
    "should_create_user": true,
    "data": { "full_name": "Agent Runner" }
  }'

JavaScript

auth-authenticate-password.ts


const  = .. ?? ''
const  = await ('https://api.codefundi.app/v2/auth/authenticate', {
  : 'POST',
  : {
    'Content-Type': 'application/json',
    'X-CodeFundi-Auth-Password': ,
  },
  : .({
    : 'password',
    : 'agent@example.com',
    : true,
    : { : 'Agent Runner' },
  }),
})
const 
const json: anyjson = await .()

Python

auth_authenticate_password.py


import json
import os
import urllib.request
 
body = {
    "auth_mode": "password",
    "email": "agent@example.com",
    "should_create_user": True,
    "data": {"full_name": "Agent Runner"},
}
req = urllib.request.Request(
    "https://api.codefundi.app/v2/auth/authenticate",
    data=json.dumps(body).encode(),
    headers={
        "Content-Type": "application/json",
        "X-CodeFundi-Auth-Password": os.environ["CODEFUNDI_TEMP_PASSWORD"],
    },
    method="POST",
)
with urllib.request.urlopen(req) as resp:
    print(resp.read().decode())

Remove stray quotes from shell examples when you paste a real password. Prefer environment variables or a secret store instead of inline literals in scripts.

Step 2: Verify email OTP

POST https://api.codefundi.app/v2/auth/verify

Summary: Exchange email + token (6-digit code) for a session and, when configured, an active API key. No X-API-Key required.

Field	Required	Description
`email`	yes	Same address used in authenticate.
`token`	yes	Code from the email.

cURL

auth-verify.sh


curl -sS -X POST "https://api.codefundi.app/v2/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@example.com",
    "token": "123456"
  }'

JavaScript

auth-verify.ts


const  = await ('https://api.codefundi.app/v2/auth/verify', {
  : 'POST',
  : { 'Content-Type': 'application/json' },
  : .({
    : 'agent@example.com',
    : '123456',
  }),
})
const 
const json: anyjson = await .()

Python

auth_verify.py


import json
import urllib.request
 
body = {"email": "agent@example.com", "token": "123456"}
req = urllib.request.Request(
    "https://api.codefundi.app/v2/auth/verify",
    data=json.dumps(body).encode(),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req) as resp:
    print(resp.read().decode())

Resend confirmation or OTP

POST https://api.codefundi.app/v2/auth/resend

Field	Required	Description
`email`	yes	Destination inbox.
`type`	no	Resend type; default `signup`. Other values: `email_change`, `email`.

cURL

auth-resend.sh


curl -sS -X POST "https://api.codefundi.app/v2/auth/resend" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@example.com",
    "type": "signup"
  }'

TypeScript

auth-resend.ts


await ('https://api.codefundi.app/v2/auth/resend', {
  : 'POST',
  : { 'Content-Type': 'application/json' },
  : .({ : 'agent@example.com', : 'signup' }),
})

Python

auth_resend.py


import json
import urllib.request
 
body = {"email": "agent@example.com", "type": "signup"}
req = urllib.request.Request(
    "https://api.codefundi.app/v2/auth/resend",
    data=json.dumps(body).encode(),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req) as resp:
    print(resp.read().decode())

Call an authenticated V2 route

After you have an active key, use it like any other V2 request:

v2-search-with-key.sh


curl -sS -X POST "https://api.codefundi.app/v2/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_UUID_API_KEY" \
  -d '{"query":"rate limiting","scope":"all"}'

More examples: V2: Search, V2: Repositories.

End-to-end sketch (bash)

Illustrative only: prefer structured JSON tooling (jq) and secure secret input in real automation.

agent-onboarding-sketch.sh


#!/usr/bin/env bash
set -euo pipefail
 
BASE_URL="https://api.codefundi.app/v2"
EMAIL="agent@example.com"
 
# 1) Request OTP (new user)
curl -sS -X POST "${BASE_URL}/auth/authenticate" \
  -H "Content-Type: application/json" \
  -d "{\"auth_mode\":\"otp\",\"email\":\"${EMAIL}\",\"should_create_user\":true}"
 
# 2) Paste code from email, then verify (replace TOKEN)
read -r -p "Enter 6-digit code: " TOKEN
curl -sS -X POST "${BASE_URL}/auth/verify" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"${EMAIL}\",\"token\":\"${TOKEN}\"}"
 
# 3) Extract api_key.key from JSON (e.g. with jq) and call V2 with X-API-Key

Treat passwords, OTP codes, refresh tokens, and API keys as secrets. Avoid echoing them into shared logs, CI output, or ticket systems.

Authoritative paths:

POST /v2/auth/authenticate
POST /v2/auth/verify
POST /v2/auth/resend

V2 overview API keys (after auth)

V2: Agent authentication

Prerequisites

Flow overview

New accounts (OTP)

Returning accounts (OTP)

Password (sign-up or sign-in)

Resend email / OTP

Step 1: Authenticate (OTP, new user)

Request body (high level)

cURL

JavaScript

Python

Step 1: Authenticate (password, new user)

cURL

JavaScript

Python

Step 2: Verify email OTP

cURL

JavaScript

Python

Resend confirmation or OTP

cURL

TypeScript

Python

Call an authenticated V2 route

End-to-end sketch (bash)

Related