@@ -56,44 +56,115 @@ DropboxApi::Client.new
5656# => #<DropboxApi::Client ...>
5757```
5858
59- Note that setting an ENV variable is only a feasible choice if you're only
60- using one account.
59+ The official documentation on the process to get an authorization code is
60+ [ here] ( https://developers.dropbox.com/es-es/oauth-guide#implementing-oauth ) ,
61+ it describes the two options listed below.
6162
62- #### Option A: Get your access token from the website
6363
64- The easiest way to obtain an access token is to get it from the Dropbox website.
65- You just need to log in to Dropbox and refer to the * developers* section, go to
66- * My apps* and select your application, you may need to create one if you
67- haven't done so yet.
64+ #### Option A: Get your access token from the website
6865
69- Under your application settings, find section * OAuth 2* . You'll find a button
70- to generate an access token.
66+ For a quick test, you can obtain an access token from the App Console in
67+ [ Dropbox's website] ( https://www.dropbox.com/developers/ ) . Select from
68+ * My apps* your application, you may need to create one if you
69+ haven't done so yet. Under your application settings, find section
70+ * OAuth 2* , there is a button to generate an access token.
7171
72- #### Option B: Use ` DropboxApi::Authenticator `
72+ #### Option B: OAuth2 Code Flow
7373
74- You can obtain an authorization code with this library:
74+ This is typically what you will use in production, you can obtain an
75+ authorization code with a 3-step process:
7576
7677``` ruby
78+ # 1. Get an authorization URL.
7779authenticator = DropboxApi ::Authenticator .new (CLIENT_ID , CLIENT_SECRET )
78- authenticator.authorize_url # => "https://www.dropbox.com/..."
80+ authenticator.auth_code. authorize_url # => "https://www.dropbox.com/..."
7981
80- # Now you need to open the authorization URL in your browser,
81- # authorize the application and copy your code .
82+ # 2. Log into Dropbox and authorize your app. You need to open the
83+ # authorization URL in your browser .
8284
83- auth_bearer = authenticator.get_token( CODE ) # => #<OAuth2::AccessToken ...>`
84- auth_bearer.token # => "VofXAX8D..."
85- # Keep this token, you'll need it to initialize a `DropboxApi::Client` object
86- ```
85+ # 3. Exchange the authorization code for a reusable access token (not visible
86+ # to the user).
87+ access_token = authenticator.auth_code.get_token( CODE ) # => #<OAuth2::AccessToken ...>`
88+ access_token.token # => "VofXAX8D..."
8789
88- #### Standard OAuth 2 flow
90+ # Keep this token, you'll need it to initialize a `DropboxApi::Client` object:
91+ client = DropboxApi ::Client .new (access_token: access_token)
92+
93+ # For backwards compatibility, the following also works:
94+ client = DropboxApi ::Client .new (access_token.token)
95+ ```
8996
90- This is what many web applications will use. The process is described in
91- Dropbox's [ OAuth guide]
92- (https://www.dropbox.com/developers/reference/oauth-guide#oauth-2-on-the-web ).
97+ ##### Integration with Rails
9398
9499If you have a Rails application, you might be interested in this [ setup
95100guide] ( http://jesus.github.io/dropbox_api/file.rails_setup.html ) .
96101
102+
103+ ##### Using refresh tokens
104+
105+ Access tokens are short-lived by default (as of September 30th, 2021),
106+ applications that require long-lived access to the API without additional
107+ interaction with the user should use refresh tokens.
108+
109+ The process is similar but a token refresh might seamlessly occur as you
110+ perform API calls. When this happens you'll need to store the
111+ new token hash if you want to continue using this session, you can use the
112+ ` on_token_refreshed ` callback to do this.
113+
114+ ``` ruby
115+ # 1. Get an authorization URL, requesting offline access type.
116+ authenticator = DropboxApi ::Authenticator .new (CLIENT_ID , CLIENT_SECRET )
117+ authenticator.auth_code.authorize_url(token_access_type: ' offline'
118+
119+ # 2. Log into Dropbox and authorize your app. You need to open the
120+ # authorization URL in your browser.
121+
122+ # 3. Exchange the authorization code for a reusable access token
123+ access_token = authenticator.auth_code.get_token(CODE ) # => #<OAuth2::AccessToken ...>`
124+
125+ # You can now use the access token to initialize a DropboxApi::Client, you
126+ # should also provide a callback function to store the updated access token
127+ # whenever it's refreshed.
128+ client = DropboxApi ::Client .new (
129+ access_token: access_token,
130+ on_token_refreshed: lambda { |new_token_hash |
131+ # token_hash is a serializable Hash, something like this:
132+ # {
133+ # "uid"=>"440",
134+ # "token_type"=>"bearer",
135+ # "scope"=>"account_info.read account_info.write...",
136+ # "account_id"=>"dbid:AABOLtA1rT6rRK4vajKZ...",
137+ # :access_token=>"sl.A5Ez_CBsqJILhDawHlmXSoZEhLZ4nuLFVRs6AJ...",
138+ # :refresh_token=>"iMg4Me_oKYUAAAAAAAAAAapQixCgwfXOxuubCuK_...",
139+ # :expires_at=>1632948328
140+ # }
141+ SomewhereSafe .save(new_token_hash)
142+ }
143+ )
144+ ```
145+
146+ Once you've gone through the process above, you can skip the steps that require
147+ user interaction in subsequent initializations of ` DropboxApi::Client ` . For
148+ example:
149+
150+ ``` ruby
151+ # 1. Initialize an authenticator
152+ authenticator = DropboxApi ::Authenticator .new (CLIENT_ID , CLIENT_SECRET )
153+
154+ # 2. Retrieve the token hash you previously stored somewhere safe, you can use
155+ # it to build a new access token.
156+ access_token = OAuth2 ::AccessToken .from_hash(authenticator, token_hash)
157+
158+ # 3. You now have an access token, so you can initialize a client like you
159+ # would normally:
160+ client = DropboxApi ::Client .new (
161+ access_token: access_token,
162+ on_token_refreshed: lambda { |new_token_hash |
163+ SomewhereSafe .save(new_token_hash)
164+ }
165+ )
166+ ```
167+
97168### Performing API calls
98169
99170Once you've initialized a client, for example:
0 commit comments