From 87ceac7b00f3167955cbaa20b068660b581f559e Mon Sep 17 00:00:00 2001
From: Joe Nelson <cred+github@begriffs.com>
Date: Thu, 10 Dec 2015 11:23:10 -0800
Subject: [PATCH] Document basic_auth.current_email()

---
 docs/examples/users.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/examples/users.md b/docs/examples/users.md
index f3b5128b6..839c02c4f 100644
--- a/docs/examples/users.md
+++ b/docs/examples/users.md
@@ -449,6 +449,32 @@ header.
 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImZvb0BiYXIuY29tIiwicm9sZSI6ImF1dGhvciJ9.KHwYdK9dAMAg-MGCQXuDiFuvbmW-y8FjfYIcMrETnto
 ```
 
+### Same-Role Users
+
+You may not want a separate db role for every user. You can distinguish
+one user from another in SQL by examining the JWT claims which
+PostgREST makes available in the SQL variable `postgrest.claims`.
+Here's a function to get the email of the currently authenticated
+user.
+
+```sql
+create or replace function
+basic_auth.current_email() returns text
+  language plpgsql
+  as $$
+begin
+  return current_setting('postgrest.claims.email');
+exception
+  -- handle unrecognized configuration parameter error
+  when undefined_object then return '';
+end;
+$$;
+```
+
+Remember that the `login` function set the claims `email` and `role`.
+You can modify `login` to set other claims as well if they are
+useful for your other SQL functions to reference later.
+
 ### Conclusion
 
 This section explained the implementation details for building a