README.markdown

Getting Started

TheKeyStone is an API wrapper around Wixels hosted user authentication and management service.

1. Go to http://thegatekeeper.wixelhq.com and request access to the service
2. Once you receive your API key, please keep it a secret

gem install thekeystone

Available Methods

Method	Description	Return Type
set_api_key(api_key)	Set the API key	None
get_user(id)	Fetch a use profile	Hash on success, false on failure
signup(params={})	Perform the user sign up and return new user ID	Hash on success, false on failure
signin(params={})	Signin a user and return the user ID	Hash on success, false on failure
verify_user(uid)	Verify a user account (optional)	true on success, false on failure
update_user(uid, params={})	Update a user profile	true on success, false on failure
generate_onetime_login_hash(email)	Generate a onetime login hash	Hash on success, false on failure
signin_with_hash(hash)	Sign in using a one-time login hash	Hash on success, false on failure
delete_user(uid)	Delete a user account	true on success, false on failure
profile_data(uid, field)	Retrieve a profile field from a user account	Hash on success, false on failure
search_by_email(email)	Find a user account using an email address	Hash on success, false on failure
reset_password(uid, new_password)	Reset a user account password	true on success, false on failure

Usage Examples

Creating a new user account

require "thekeystone"

api = TheKeyStone.new('[your API key]');

new_user = api.signup(:email => "[email protected]", :password => "mypassword") 
# new_user = {"uid"=>"4f19494e601cae0001000001"}

if !new_user
	puts api.last_error
else
	pp api.get_user(new_user["uid"]) 
end

Authenticate a user

user = api.signin(:email => "[email protected]", :password => "mypassword")

if !user
	puts api.last_error
else
	pp api.get_user(user["uid"]) # you should store user["uid"] in your session at this point
end

Verify a user account

This is an optional feature that is present incase your application requires user verification.

api.verify_user('[a user id]') # => true/false

Fetch a user profile

Keep in mind that all profile fields are returned as a Ruby hash.

profile = api.get_user('[a user id]')

# Response:

{
 "email"=>"[email protected]",
 "username"=>nil,
 "full_name"=>"",
 "timezone"=>"London",
 "twitter"=>"",
 "facebook"=>"",
 "github"=>"",
 "linkedin"=>"",
 "about"=>"",
 "latlng"=>"",
 "gender"=>"",
 "phone"=>"",
 "address"=>"",
 "user_api_key"=>"7801cba92f3fe4b5a00070316ed66aac",
 "converted"=>false,
 "conversion_date"=>nil,
 "last_login"=>"2012-01-20T14:05:05+00:00"
}

Update a users profile

You are able to update multiple fields in a single request.

api.update_user(
	"[a user ID]", :twitter => "@SeanNieuwoudt", :github => "http://github.com/organizations/Wixel"
)

Using the one-time log in hash

A one-time log in hash is used when a user has forgotten their password. Your user enters their email address on your site and you pass it along to the API. A log in hash will be generated and returned.

You will need to email this to the user and allow them to log in by clicking on a link that re-connects to the API and authenticates the user using the hash.

This hash can only be used once and is destroyed after usage.

hash = api.generate_onetime_login_hash('[email protected]') 
# hash = {"login_hash"=>"a9ce493328c52dfdebbc4d1776881dc7"}
	
user = api.signin_with_hash(hash["login_hash"])
# user = {"uid"=>"4f197491912c0c000100003f"}

Fetching profile information

If you need to fetch the entire user profile in a single request, please use the api.get_user method instead.

data = api.profile_data('[a user ID]', 'email')
# data = {"email"=>"[email protected]"}

Finding users by email

Keep in mind that you can only find one account at a time and queries are only specific to one API key per request.

user = api.search_by_email('[email protected]')

Resetting user passwords

api.reset_password('[a user ID]','my_new_password')