token refresh

README.markdown

@@ -10,7 +10,7 @@ RubyBox provides a simple, chainable, feature-rich client for [Box's 2.0 API](ht
 Authorization
 -------------
 
-RubyBox uses Box's OAuth2 Implementaton, Here are the steps involved in authorizing a client:
+RubyBox uses Box's OAuth2 Implementation, Here are the steps involved in authorizing a client:
 
 __1)__ Get the authorization url.
 
@@ -25,40 +25,57 @@ session = RubyBox::Session.new({
 authorize_url = session.authorize_url('https://redirect-url-in-app-settings')
 ```
 
-__2)__ After redirecting to the authorize_url, exchange the _code_ given for an _access\_token_
+__2)__ After redirecting to the authorize_url, exchange the `code` given for an `access_token`
 
 ```ruby
 @token = session.get_access_token('code-returned-to-redirect_url')
 p '@token.token' # the access token.
 p '@token.refresh_token' # token that can be exchanged for a new access_token once the access_token expires.
-
-# refreshing token.
-
-session = RubyBox::Session.new({
-  client_id: 'your-client-id',
-  client_secret: 'your-client-secret',
-  access_token: 'original-access-token' 
-})
-
-# you need to persist this somehow. the refresh token will change every time you use it
-@token = session.refresh_token('your-refresh-token')
-save_me_somehow(@token.refresh_token)
 ```
+See [Storing Tokens](storing_token) for important information on persisting these tokens.
 
-__3)__ Create a client using a session initialized with the _access\_token_.
+__3)__ Create a client using a session initialized with the `access_token` and `refresh_token`.
 
 ```ruby
 require 'ruby-box'
 
-session = RubyBox::Session.new({
+session = MyBoxSession.new({
   client_id: 'your-client-id',
   client_secret: 'your-client-secret',
-  access_token: 'access-token'
+  access_token: 'access-token',
+  refresh_token: 'refresh-token'
 })
 
 client = RubyBox::Client.new(session)
 ```
 
+Storing Tokens <a name='storing_tokens'><a>
+=====
+Box.com tokens are short lived. Once they expire, the refresh_token may be used _once_ to issue a new access_token
+and refresh_token pair. It is important to securely persist theses initially as well as any time a refresh token
+is used to issue new tokens.
+
+ruby-box will automatically attempt to refresh the token if it receives a response that the access_token is expired.
+Subclassing Session will allow you to save the new tokens:
+
+```ruby
+class MyBoxSession < RubyBox::Session
+  # override call to refresh token so we can update the tokens store
+  def refresh_token(refresh_token)
+    ut = MyTokens.where(refresh_token: refresh_token, provider: 'box').first
+    begin
+      super
+      ut.access_token = @access_token.token
+      ut.refresh_token = @access_token.refresh_token
+      ut.save!
+    rescue OAuth2::Error => e
+      # token pair must just be bad
+      ut.destroy
+    end
+  end
+end
+```
+
 Usage
 =====