NE_SET_SERVER_AUTH(3)

💅 NE_SET_SERVER_AUTH(3) — neon API reference, bestie edition 🎀

okay so first things first: this is a page from the neon API reference, section 3 of the manual, and it's all about auth callbacks. yes that auth. the "who even ARE you" moment between your code and a server. let's get into it 💖

---

✨ NAME ✨

ne_set_server_auth, ne_set_proxy_auth, ne_forget_auth — the trio that registers your authentication callbacks 🫶

---

🌸 SYNOPSIS 🌸

#include <ne_auth.h>

typedef int (*ne_auth_creds)(void *userdata, const char *realm,
                             int attempt, char *username,
                             char *password);

void ne_set_server_auth(ne_session *session, ne_auth_creds callback,
                        void *userdata);

void ne_set_proxy_auth(ne_session *session, ne_auth_creds callback,
                       void *userdata);

void ne_forget_auth(ne_session *session);

---

🦋 DESCRIPTION 🦋

so the ne_auth_creds function type defines a callback that gets invoked when a server or a proxy server needs user authentication for a particular request. very "prove it's you" energy 💅

• the realm string? that's supplied by the server, not you. it's their vibe check, not yours.
• the attempt is a counter — it tells you how many times the request has been retried with different authentication credentials. the first time the callback is invoked for a particular request, attempt will be zero.

to retry the request using new authentication credentials, your callback should return zero, and the username and password buffers must contain NUL-terminated strings. the NE_ABUFSIZ constant gives the size of these buffers — that's your limit, don't overflow it, i'm begging 😭

💡 Tip: if you only wish to allow the user one attempt to enter credentials, use the value of the attempt parameter as the return value of the callback. iconic little trick, lowkey elegant, no cap.

to abort the request, the callback should return a non-zero value — and in that case the contents of the username and password buffers are just ignored. like, thanks for nothing, moving on 💀

and then there's ne_forget_auth — the function you call to discard the cached authentication credentials. memory wipe. fresh start. main character energy 🔥

---

🎀 EXAMPLES 🎀

/* Function which prompts for a line of user input: */
extern char *prompt_for(const char *prompt);

static int
my_auth(void *userdata, const char *realm, int attempts,
        char *username, char *password)
{
   strncpy(username, prompt_for("Username: "), NE_ABUFSIZ);
   strncpy(password, prompt_for("Password: "), NE_ABUFSIZ);
   return attempts;
}

int main(...)
{
   ne_session *sess = ne_session_create(...);

   ne_set_server_auth(sess, my_auth, NULL);

   /* ... */
}

see how my_auth just hands attempts right back as its return value? that's the one-shot trick from the tip above, working exactly as advertised. slay ✨

---

👑 COPYRIGHT 👑

Copyright © 2001-2026 Joe Orton

---

and that's the whole page, bestie — no notes, ate and left no crumbs 🍓

🌷 cute little sign-off: this was NE_SET_SERVER_AUTH(3) from the neon API reference, dated 03/20/2026, and that version line down at the bottom of the original? consider it mentioned. mwah 💜 🧚