Permalink
Browse files

Add authorization curl examples

And explicitly call out where we need the Content-type header to be
application/x-www-form-urlencoded (usually just in authentication).
  • Loading branch information...
1 parent 16f8001 commit 8e4bd5093d5272ef16096a2e0bcb9c44f0e8bd8b @mthurman mthurman committed Apr 3, 2014
@@ -19,6 +19,22 @@ with URL-encoded POST body:
&client_secret=[your client secret]
&grant_type=client_credentials
+Example:
+
+<%= curl_example(:post, "access_token", :none, {
+ :subdomain => "account",
+ :path_prefix => "/oauth/",
+ :pretty_json => false,
+ :token => nil,
+ :content_type => nil,
+ :data => {
+ "grant_type" => "client_credentials",
+ "client_id" => "[your client_id]",
+ "client_secret" => "[your client secret]",
+ }
+}) %>
+
+
> We also accept the `client_id` and `client_secret` parameters via the Authorization header, as described in [section 2.3.1 of the OAuth 2 spec](http://tools.ietf.org/html/rfc6749#section-2.3.1).
App.net will respond with a JSON-encoded token:
@@ -49,6 +49,24 @@ Once you have been approved, using the password flow is pretty straightforward:
&password=[user's password]
&scope=[scopes separated by spaces]
+ Example:
+
+ <%= curl_example(:post, "access_token", :none, {
+ :subdomain => "account",
+ :path_prefix => "/oauth/",
+ :pretty_json => false,
+ :token => nil,
+ :content_type => nil,
+ :data => {
+ "grant_type" => "password",
+ "client_id" => "[your client_id]",
+ "password_grant_secret" => "[your password grant secret that was emailed to you]",
+ "username" => "[user's email address or username]",
+ "password" => "[user's password]",
+ "scope" => "[scopes separated by spaces]",
+ }
+ }) %>
+
> The use of `password_grant_secret` diverges from the OAuth 2.0 specification. `password_grant_secret` is a special token that we'll send you when your use of the password flow is approved.
> **You can require app-specific passwords** by providing a `require_app_specific_password=1` URL parameter. **[Two-Factor Auth users](http://blog.app.net/2013/03/13/added-security-for-your-app-net-account/) must use app-specific passwords** regardless of this parameter. We strongly encourage the use of app-specific passwords by all users as they significantly increase account security.
@@ -45,6 +45,23 @@ Your `redirect_uri` must be registered with App.net before you can use it.
&redirect_uri=[your registered redirect URI]
&code=[code received from redirect URI]
+ Example:
+
+ <%= curl_example(:post, "access_token", :none, {
+ :subdomain => "account",
+ :path_prefix => "/oauth/",
+ :pretty_json => false,
+ :token => nil,
+ :content_type => nil,
+ :data => {
+ "grant_type" => "authorization_code",
+ "client_id" => "[your client_id]",
+ "client_secret" => "[your client secret]",
+ "redirect_uri" => "[your registered redirect URI]",
+ "code" => "[code received in the previous step]"
+ }
+ }) %>
+
> We also accept the `client_id` and `client_secret` parameters via the Authorization header, as described in [section 2.3.1 of the OAuth 2 spec](http://tools.ietf.org/html/rfc6749#section-2.3.1).
1. App.net will respond with a JSON-encoded token: `{"access_token": "[user access token]", "token": {...Token object...}}`
@@ -45,6 +45,20 @@ Intentionally not addressed in this document are the following:
> For App.net, the OAuth token endpoint is: `https://account.app.net/oauth/access_token`
+ Example:
+
+ <%= curl_example(:post, "access_token", :none, {
+ :subdomain => "account",
+ :path_prefix => "/oauth/",
+ :pretty_json => false,
+ :content_type => nil,
+ :data => {
+ "grant_type" => "delegate",
+ "delegate_client_id" => "[your client_id]",
+ }
+ }) %>
+
+
1. The authorized client makes a request to the delegate client with two additional headers, `Identity-Delegate-Token` and `Identity-Delegate-Endpoint`:
POST /protected/resource HTTP/1.1
@@ -60,7 +74,26 @@ Intentionally not addressed in this document are the following:
> The delegate token and delegate endpoint may also be sent as delegate_token and delegate_endpoint in the query string or POST body.
-1. The delegate client identifies the resource server by using the `Identity-Delegate-Endpoint` header and makes a request to that endpoint with the Authorization header set.
+ Example:
+
+ <%= curl_example(:post, "protected/resource", :none, {
+ :subdomain => "delegate-client",
+ :domain => "example.com",
+ :path_prefix => "/",
+ :pretty_json => false,
+ :content_type => nil,
+ :token => nil,
+ :headers => {
+ "Identity-Delegate-Token" => "[delegate_token from previous step]",
+ "Identity-Delegate-Endpoint" => "https://alpha-api.app.net/stream/0/token",
+ },
+ :data => {
+ "do_some_stuff" => "1",
+ "fo_reals" => "1",
+ }
+ }) %>
+
+1. The delegate client identifies the resource server (App.net) by using the `Identity-Delegate-Endpoint` header and makes a request to that endpoint with the Authorization header set.
> The query string parameters `delegate_token`, `client_id` and `client_secret` may be used in place of HTTP headers if desired.
@@ -100,12 +133,22 @@ Intentionally not addressed in this document are the following:
}
}
- The resource server replies with an implementation-dependent description of the current user, which must include the client_id the authorized client. In the case of App.net, this is the Token object of the authorizing client's access_token as returned by the [Retrieve current Token](/reference/resources/token/#retrieve-current-token) endpoint.
+ App.net replies with information about the authorized delegate token. This is the Token object of the authorizing client's access_token as returned by the [Retrieve current Token](/reference/resources/token/#retrieve-current-token) endpoint.
The delegate client may verify that the authorized client matches some external authentication scheme and/or list of authorized applications. If the delegate token is not valid for the delegate client's client_id, this call will return a `401 Unauthorized`.
> For App.net, the identity delegation endpoint is: `https://alpha-api.app.net/stream/0/token`
+ Example:
+
+ <%= curl_example(:get, "token", :none, {
+ :pretty_json => false,
+ :headers => {
+ "Authorization" => "Basic [base64(client_id + ':' + client_secret)]",
+ "Identity-Delegate-Token" => "[delegate_token]",
+ },
+ }) %>
+
## Notes
1. `delegate_token`s are valid as long as their associated `access_token`s are valid.
View
@@ -160,7 +160,10 @@ def curl_example(method, path, response_key, options = {}, &block)
end
- if [:post, :put, :patch].include? method and options[:content_type] and (options[:data_binary] or not options[:data].empty?)
+ if [:post, :put, :patch].include? method and (options[:data_binary] or not options[:data].empty?)
+ unless options[:content_type]
+ options[:content_type] = "application/x-www-form-urlencoded"
+ end
options[:headers]["Content-Type"] = options[:content_type]
end

0 comments on commit 8e4bd50

Please sign in to comment.