-
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
API endpoint descriptions and examples
Mastermike edited this page Nov 20, 2015
·
27 revisions
What follows are descriptions, sample usage, outputs, and server outputs for each of the Doorkeeper API endpoints.
Provides a page with the authorization code.
curl http://localhost:3000/oauth/authorize/fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0
HTML page that includes the following content:
<h3>Authorization code:</h3>
<code id="authorization_code">fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0</code>
Started GET "/oauth/authorize/fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0" for 127.0.0.1 at 2014-02-26 17:42:14 -0500
Processing by Doorkeeper::AuthorizationsController#show as */*
Parameters: {"code"=>"fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0"}
User Load (0.1ms) SELECT "users".* FROM "users" WHERE "users"."email" IS NULL LIMIT 1
Rendered /Users/dclo/.rbenv/versions/1.9.3-p484/lib/ruby/gems/1.9.1/bundler/gems/doorkeeper-e0c826aff1ec/app/views/doorkeeper/authorizations/show.html.erb within layouts/application (4.8ms)
Rendered layouts/_header.html.erb (0.4ms)
Rendered layouts/_flash.html.erb (0.5ms)
Post here with response_type=code, client_id, client_secret, redirect_uri, and username. Will create and return an authorization code, then redirect to GET /oauth/authorize/:code with the authorization code. This endpoint
corresponds to the OAuth 2 authorization endpoint, section 3.1
curl -F response_type=code \
-F client_id=9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f \
-F client_secret=d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2 \
-F redirect_uri=urn:ietf:wg:oauth:2.0:oob \
-F username=user@example.com \
-X POST http://localhost:3000/oauth/authorize
Redirect to the GET /oauth/authorize/:code path.
<html><body>You are being <a href="http://localhost:3000/oauth/authorize/fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0">redirected</a>.</body></html>
Started POST "/oauth/authorize" for 127.0.0.1 at 2014-02-26 17:36:40 -0500
Processing by Doorkeeper::AuthorizationsController#create as */*
Parameters: {"response_type"=>"code", "client_id"=>"9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f", "client_secret"=>"d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2", "redirect_uri"=>"urn:ietf:wg:oauth:2.0:oob", "username"=>"user@example.com"}
User Load (0.1ms) SELECT "users".* FROM "users" WHERE "users"."email" = 'user@example.com' LIMIT 1
Doorkeeper::Application Load (0.2ms) SELECT "oauth_applications".* FROM "oauth_applications" WHERE "oauth_applications"."uid" = '9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f' LIMIT 1
CACHE (0.0ms) SELECT "users".* FROM "users" WHERE "users"."email" = 'user@example.com' LIMIT 1
(0.1ms) SELECT 1 FROM "oauth_access_grants" WHERE "oauth_access_grants"."token" = 'fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0' LIMIT 1
SQL (0.5ms) INSERT INTO "oauth_access_grants" ("application_id", "created_at", "expires_in", "redirect_uri", "resource_owner_id", "revoked_at", "scopes", "token") VALUES (?, ?, ?, ?, ?, ?, ?, ?) [["application_id", 1], ["created_at", Wed, 26 Feb 2014 22:36:48 UTC +00:00], ["expires_in", 600], ["redirect_uri", "urn:ietf:wg:oauth:2.0:oob"], ["resource_owner_id", 1], ["revoked_at", nil], ["scopes", "public"], ["token", "fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0"]]
Redirected to http://localhost:3000/oauth/authorize/fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0
Revoke OAuth authorization, deletes the access token.
curl -F response_type=token \
-F access_token=dbaf97579826846f45fa37a923a4387474070e04323b22f499b7227a860bac920b0ee6560c2 \
-F client_id=9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f \
-F client_secret=d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2 \
-F redirect_uri=urn:ietf:wg:oauth:2.0:oob \
-F username=user@example.com \
-X DELETE http://localhost:3000/oauth/authorize
Redirect to redirect_uri
Started DELETE "/oauth/authorize" for 127.0.0.1 at 2014-02-26 19:53:59 -0500
Processing by Doorkeeper::AuthorizationsController#destroy as */*
Parameters: {"response_type"=>"token", "access_token"=>"dbaf97579826846f45fa37a923a4387474070e04323b22f499b7227a860bac920b0ee6560c2", "client_id"=>"9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f", "client_secret"=>"d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2", "redirect_uri"=>"urn:ietf:wg:oauth:2.0:oob", "username"=>"user@example.com"}
User Load (0.1ms) SELECT "users".* FROM "users" WHERE "users"."email" = 'user@example.com' LIMIT 1
Doorkeeper::Application Load (0.2ms) SELECT "oauth_applications".* FROM "oauth_applications" WHERE "oauth_applications"."uid" = '9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f' LIMIT 1
CACHE (0.0ms) SELECT "users".* FROM "users" WHERE "users"."email" = 'user@example.com' LIMIT 1
Redirected to urn:ietf:wg:oauth:2.0:oob#error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.
Completed 302 Found in 1621ms
Post here with authorization code for authorization code grant type or username and password for password grant type, or refresh token for refresh token type. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC
curl -F grant_type=authorization_code \
-F client_id=9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f \
-F client_secret=d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2 \
-F code=fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0 \
-F redirect_uri=urn:ietf:wg:oauth:2.0:oob \
-X POST http://localhost:3000/oauth/token
{"access_token":"dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781","token_type":"bearer","expires_in":7200,"refresh_token":"76ba4c5c75c96f6087f58a4de10be6c00b29ea1ddc3b2022ee2016d1363e3a7c","scope":"public"}
Started POST "/oauth/token" for 127.0.0.1 at 2014-02-26 17:52:28 -0500
Processing by Doorkeeper::TokensController#create as */*
Parameters: {"grant_type"=>"authorization_code", "client_id"=>"9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f", "client_secret"=>"d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2", "code"=>"7f0af71e623fc76cc0bf91bbcf5686c450b9a2fcacfd31c0b069431a0cb5328c", "redirect_uri"=>"urn:ietf:wg:oauth:2.0:oob"}
Doorkeeper::AccessGrant Load (0.2ms) SELECT "oauth_access_grants".* FROM "oauth_access_grants" WHERE "oauth_access_grants"."token" = '7f0af71e623fc76cc0bf91bbcf5686c450b9a2fcacfd31c0b069431a0cb5328c' LIMIT 1
Doorkeeper::Application Load (0.2ms) SELECT "oauth_applications".* FROM "oauth_applications" WHERE "oauth_applications"."uid" = '9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f' AND "oauth_applications"."secret" = 'd6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2' LIMIT 1
SQL (2.7ms) UPDATE "oauth_access_grants" SET "revoked_at" = '2014-02-26 22:52:28' WHERE "oauth_access_grants"."id" = 5
(0.2ms) SELECT 1 FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."token" = 'dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781' LIMIT 1
(0.1ms) SELECT 1 FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."refresh_token" = '76ba4c5c75c96f6087f58a4de10be6c00b29ea1ddc3b2022ee2016d1363e3a7c' LIMIT 1
SQL (0.6ms) INSERT INTO "oauth_access_tokens" ("application_id", "created_at", "expires_in", "refresh_token", "resource_owner_id", "revoked_at", "scopes", "token") VALUES (?, ?, ?, ?, ?, ?, ?, ?) [["application_id", 1], ["created_at", Wed, 26 Feb 2014 22:52:28 UTC +00:00], ["expires_in", 7200], ["refresh_token", "76ba4c5c75c96f6087f58a4de10be6c00b29ea1ddc3b2022ee2016d1363e3a7c"], ["resource_owner_id", 1], ["revoked_at", nil], ["scopes", "public"], ["token", "dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781"]]
Completed 200 OK in 18ms
Versions of Doorkeeper at and prior to 0.7.x might also require the client_id and client_secret.
This API call will invoke the resource_owner_from_credentials defined in config/initializers/doorkeeper.rb
to convert the username and password into a user.
curl -F grant_type=password \
-F username=user@example.com \
-F password=doorkeeper \
-X POST http://localhost:3000/oauth/token
{"access_token":"0ddb922452c983a70566e30dce16e2017db335103e35d783874c448862a78168",
"token_type":"bearer",
"expires_in":7200,
"refresh_token":"f2188c4165d912524e04c6496d10f06803cc08ed50271a0b0a73061e3ac1c06c",
"scope":"public"}
Started POST "/oauth/token" for 127.0.0.1 at 2014-02-26 17:56:17 -0500
Processing by Doorkeeper::TokensController#create as */*
Parameters: {"grant_type"=>"password", "username"=>"user@example.com", "password"=>"[FILTERED]"}
User Load (0.2ms) SELECT "users".* FROM "users" WHERE "users"."email" = 'user@example.com' LIMIT 1
(0.2ms) SELECT 1 FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."token" = '0ddb922452c983a70566e30dce16e2017db335103e35d783874c448862a78168' LIMIT 1
(0.1ms) SELECT 1 FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."refresh_token" = 'f2188c4165d912524e04c6496d10f06803cc08ed50271a0b0a73061e3ac1c06c' LIMIT 1
SQL (0.6ms) INSERT INTO "oauth_access_tokens" ("application_id", "created_at", "expires_in", "refresh_token", "resource_owner_id", "revoked_at", "scopes", "token") VALUES (?, ?, ?, ?, ?, ?, ?, ?) [["application_id", nil], ["created_at", Wed, 26 Feb 2014 22:56:17 UTC +00:00], ["expires_in", 7200], ["refresh_token", "f2188c4165d912524e04c6496d10f06803cc08ed50271a0b0a73061e3ac1c06c"], ["resource_owner_id", 1], ["revoked_at", nil], ["scopes", "public"], ["token", "0ddb922452c983a70566e30dce16e2017db335103e35d783874c448862a78168"]]
Completed 200 OK in 106ms
curl -F grant_type=refresh_token \
-F client_id=9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f \
-F client_secret=d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2 \
-F refresh_token=c65b265611713028344a2c285dfdc4e28f9ce2dbc36b9f7e12f626a3d106a304 \
-X POST http://localhost:3000/oauth/token
{"access_token":"ad0b5847cb7d254f1e2ff1910275fe9dcb95345c9d54502d156fe35a37b93e80",
"token_type":"bearer",
"expires_in":30,
"refresh_token":"cc38f78a5b8abe8ee81cdf25b1ca74c3fa10c3da2309de5ac37fde00cbcf2815",
"scope":"public"}
Started POST "/oauth/token" for 127.0.0.1 at 2014-02-26 20:06:38 -0500
Processing by Doorkeeper::TokensController#create as */*
Parameters: {"grant_type"=>"refresh_token", "client_id"=>"9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f", "client_secret"=>"d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2", "refresh_token"=>"c65b265611713028344a2c285dfdc4e28f9ce2dbc36b9f7e12f626a3d106a304"}
Doorkeeper::AccessToken Load (0.2ms) SELECT "oauth_access_tokens".* FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."refresh_token" = 'c65b265611713028344a2c285dfdc4e28f9ce2dbc36b9f7e12f626a3d106a304' LIMIT 1
Doorkeeper::Application Load (0.3ms) SELECT "oauth_applications".* FROM "oauth_applications" WHERE "oauth_applications"."uid" = '9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f' AND "oauth_applications"."secret" = 'd6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2' LIMIT 1
SQL (1.0ms) UPDATE "oauth_access_tokens" SET "revoked_at" = '2014-02-27 01:06:38' WHERE "oauth_access_tokens"."id" = 88
(0.3ms) SELECT 1 FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."token" = 'ad0b5847cb7d254f1e2ff1910275fe9dcb95345c9d54502d156fe35a37b93e80' LIMIT 1
(0.1ms) SELECT 1 FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."refresh_token" = 'cc38f78a5b8abe8ee81cdf25b1ca74c3fa10c3da2309de5ac37fde00cbcf2815' LIMIT 1
SQL (0.9ms) INSERT INTO "oauth_access_tokens" ("application_id", "created_at", "expires_in", "refresh_token", "resource_owner_id", "revoked_at", "scopes", "token") VALUES (?, ?, ?, ?, ?, ?, ?, ?) [["application_id", 1], ["created_at", Thu, 27 Feb 2014 01:06:38 UTC +00:00], ["expires_in", 30], ["refresh_token", "cc38f78a5b8abe8ee81cdf25b1ca74c3fa10c3da2309de5ac37fde00cbcf2815"], ["resource_owner_id", 1], ["revoked_at", nil], ["scopes", "public"], ["token", "ad0b5847cb7d254f1e2ff1910275fe9dcb95345c9d54502d156fe35a37b93e80"]]
Completed 200 OK in 18ms
{"error":"invalid_grant",
"error_description":"The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."}
Started POST "/oauth/token" for 127.0.0.1 at 2015-08-24 16:59:31 -0700
Processing by Doorkeeper::TokensController#create as */*
Parameters: {"grant_type"=>"password", "username"=>"grape@swagger.com", "password"=>"[FILTERED]"}
User Load (0.1ms) SELECT "users".* FROM "users" WHERE "users"."email" = ? ORDER BY "users"."id" ASC LIMIT 1 [["email", "grape@swagger.com"]]
Completed 401 Unauthorized in 94ms
curl http://localhost:3000/oauth/applications
HTML page with tabular list of authorized application clients
<tr id="application_1">
<td><a href="/oauth/applications/1">Doorkeeper Sinatra Client</a></td>
<td>urn:ietf:wg:oauth:2.0:oob</td>
<td><a href="/oauth/applications/1/edit">Edit</a></td>
<td><a href="/oauth/applications/1" data-confirm="Are you sure?" data-method="delete" rel="nofollow">Destroy</a></td>
</tr>
Started GET "/oauth/applications" for 127.0.0.1 at 2014-02-26 18:01:41 -0500
Processing by Doorkeeper::ApplicationsController#index as */*
Doorkeeper::Application Load (0.1ms) SELECT "oauth_applications".* FROM "oauth_applications"
Rendered doorkeeper/applications/index.html.erb within layouts/application (3.6ms)
Rendered layouts/_header.html.erb (0.0ms)
Rendered layouts/_flash.html.erb (0.0ms)
Completed 200 OK in 18ms (Views: 15.8ms | ActiveRecord: 0.7ms)
Creates an authorized application with client id and secret. This is form submission from the page served by /oauth/applications/new
Serves a web form for editing a new authorized api client.
Serves a web form for editing the specified authorized api client.
Displays a web page with details of a specified authorized api client.
Updates an authorized api client. This is form submission from the page served by /oauth/applications/:id/edit
Deletes the specified authorized api client
Web user interface for logged-in user displays a list of api client authorizations along with delete buttons.
Invokes the resource_owner_authenticator method defined in config/initializers/doorkeeper.rb to authenticate the current user.
curl -F username=user@example.com \
-X GET http://localhost:3000/oauth/authorized_applications
HTML page includes table of api client authorizations
<tr>
<td>Doorkeeper Sinatra Client</td>
<td>2014-01-28 17:03:24 UTC</td>
<td><a href="/oauth/authorized_applications/1" class="btn danger" data-confirm="Are you sure?" data-method="delete" rel="nofollow">Revoke</a></td>
</tr>
Started GET "/oauth/authorized_applications" for 127.0.0.1 at 2014-02-26 18:36:46 -0500
Processing by Doorkeeper::AuthorizedApplicationsController#index as */*
Parameters: {"username"=>"user@example.com"}
User Load (0.2ms) SELECT "users".* FROM "users" WHERE "users"."email" = 'user@example.com' LIMIT 1
CACHE (0.0ms) SELECT "users".* FROM "users" WHERE "users"."email" = 'user@example.com' LIMIT 1
Doorkeeper::Application Load (0.6ms) SELECT "oauth_applications".* FROM "oauth_applications" INNER JOIN "oauth_access_tokens" ON "oauth_access_tokens"."application_id" = "oauth_applications"."id" AND "oauth_access_tokens"."revoked_at" IS NULL INNER JOIN "oauth_applications" "authorized_applications_oauth_applications" ON "authorized_applications_oauth_applications"."id" = "oauth_access_tokens"."application_id" WHERE "oauth_access_tokens"."resource_owner_id" = 1 AND "oauth_access_tokens"."revoked_at" IS NULL GROUP BY oauth_applications.id,oauth_applications.name,oauth_applications.uid,oauth_applications.secret,oauth_applications.redirect_uri,oauth_applications.created_at,oauth_applications.updated_at,oauth_applications.owner_id,oauth_applications.owner_type
Rendered doorkeeper/authorized_applications/index.html.erb within layouts/application (44.5ms)
Rendered layouts/_header.html.erb (0.0ms)
Rendered layouts/_flash.html.erb (0.0ms)
Completed 200 OK in 5593ms (Views: 58.4ms | ActiveRecord: 1.8ms)
Destroys the identified api client authorization from a user.
Invokes the resource_owner_authenticator method defined in config/initializers/doorkeeper.rb to authenticate the current user.
curl -F username=user@example.com \
-X DELETE http://localhost:3000/oauth/authorized_applications/1
redirect to /oauth/authorized_applications
Started DELETE "/oauth/authorized_applications/1" for 127.0.0.1 at 2014-02-26 18:50:03 -0500
Processing by Doorkeeper::AuthorizedApplicationsController#destroy as */*
Parameters: {"username"=>"user@example.com", "id"=>"1"}
User Load (0.1ms) SELECT "users".* FROM "users" WHERE "users"."email" = 'user@example.com' LIMIT 1
CACHE (0.0ms) SELECT "users".* FROM "users" WHERE "users"."email" = 'user@example.com' LIMIT 1
Doorkeeper::AccessToken Load (0.7ms) SELECT "oauth_access_tokens".* FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."application_id" = 1 AND "oauth_access_tokens"."resource_owner_id" = 1 AND "oauth_access_tokens"."revoked_at" IS NULL
SQL (3.5ms) UPDATE "oauth_access_tokens" SET "revoked_at" = '2014-02-26 23:50:10' WHERE "oauth_access_tokens"."id" = 2
SQL (0.9ms) UPDATE "oauth_access_tokens" SET "revoked_at" = '2014-02-26 23:50:10' WHERE "oauth_access_tokens"."id" = 83
Redirected to http://localhost:3000/oauth/authorized_applications
Completed 302 Found in 6314ms
Shows details about the token used for authentication
curl -H "Authorization: Bearer 53cff8f4a549beb1c38704158b0f6608a2382f094b6947ecc35c2eed4146a17c" \
localhost:3000/oauth/token/info
{"resource_owner_id":1,
"scopes":[],
"expires_in_seconds":7178,
"application":{"uid":null},
"created_at":1440460991}
Started GET "/oauth/token/info" for 127.0.0.1 at 2015-08-24 17:03:32 -0700
Processing by Doorkeeper::TokenInfoController#show as */*
Doorkeeper::AccessToken Load (0.3ms) SELECT "oauth_access_tokens".* FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."token" = ? LIMIT 1 [["token", "bea06cb4f681e04f5a3bbfe699ad1b7e8cb40c2a57f974370da5f537d71509be"]]
Completed 200 OK in 2ms
{"error":"invalid_request",
"error_description":"The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed."}
Started GET "/oauth/token/info" for 127.0.0.1 at 2015-08-24 17:06:49 -0700
Processing by Doorkeeper::TokenInfoController#show as */*
Doorkeeper::AccessToken Load (0.1ms) SELECT "oauth_access_tokens".* FROM "oauth_access_tokens" WHERE "oauth_access_tokens"."token" = ? LIMIT 1 [["token", "bea06cb4f681e04f5a3bbfe699ad1b7e8cb40c2a57f974371509be"]]
Completed 401 Unauthorized in 1ms
Revokes the given token, requires authentication
curl -F token=53cff8f4a549beb1c38704158b0f6608a2382f094b6947ecc35c2eed4146a17c \
-H "Authorization: Bearer 53cff8f4a549beb1c38704158b0f6608a2382f094b6947ecc35c2eed4146a17c" \
-X POST localhost:3000/oauth/revoke
Always returns 200 OK, even if token doesn't exist or has already been revoked.