Developer / REST API v1

OAuth Authorizations API

babylon-projekt/developer articles

This document describes the oauth api for accessing resources within the babylon-research-framework.

Get your grants

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the list your authorizations API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user.

GET /applications/grants

Response

[
  {
    id: 153,
    url: "http://localhost:3000/api/applications/grants/153",
    app: {
      url: "http://localhost:3000/api/applications/8081134e6b0692628719026f0578a0182454757cfa02f5d240f374b64e52e487",
      name: "literature",
      client_id: "8081134e6b0692628719026f0578a0182454757cfa02f5d240f374b64e52e487"
    },
    created_at: "2017-11-08T14:15:04.332Z",
    scopes: [ ]
  }
]

Get a single grant

GET /applications/grants/:id

List your authorizations

GET /authorizations

Response

[
  {
    id: 6,
    url: "http://localhost:3000/api/authorizations/6",
    scopes: [ ],
    token: "",
    user_permissions: {
      create: true,
      read: true,
      update: true,
      destroy: true,
      extra: {
        manage: true,
        comment: true,
        publish: true
      }
    },
    app: {
      url: "http://localhost:3000/api/applications/45940b256cc1c7ba9b1781d2a5a40468a81ede4b1818f9a69f96fc854b7ea1ab",
      name: "Connector",
      client_id: "45940b256cc1c7ba9b1781d2a5a40468a81ede4b1818f9a69f96fc854b7ea1ab"
    },
    updated_at: "2017-11-01T10:47:04.420Z",
    created_at: "2017-10-27T10:05:12.212Z"
  }
]

Get a single authorization

GET /authorizations/:id

There are two levels of permissions:
1. User-Permissions: As a app owner, you can grant create, read, update, destroy and manager, publish, comment permissions to a user or group (user_permissions).
2. App-Permissions: These define what resources in babylon-online the App can access via the API (scopes, visible in grants also).

Get an authorization for a specific app

This method will return an authorization for the specified OAuth application. The URL must include the 20 character client ID for the OAuth app that is requesting the token. It returns the user's existing authorization for the application if one is present, together with the user permissions, a users-list and a groups-list.

GET /authorizations/clients/:client_id

Response if returning an existing token

{
  id: 6,
  url: "http://localhost:3000/api/authorizations/6",
  scopes: [ ],
  token: "4c05bc1cd4d937b9c291f378665db655febdd79afe46a546634097ac934c13bc",
  user_permissions: {
    create: true,
    read: true,
    update: true,
    destroy: true,
    extra: {
      manage: true,
      comment: true,
      publish: true
    }
  },
  app: {
    url: "http://localhost:3000/api/applications/45940b256cc1c7ba9b1781d2a5a40468a81ede4b1818f9a69f96fc854b7ea1ab",
    name: "Connector",
    client_id: "45940b256cc1c7ba9b1781d2a5a40468a81ede4b1818f9a69f96fc854b7ea1ab"
  },
  updated_at: "2017-11-01T10:47:04.420Z",
  created_at: "2017-10-27T10:05:12.212Z",
  project_accessors: [
    {
      id: 1,
      name: "Babylon",
      member_ids: [1,2,3,4,6,7,8],
      oauth_application_uids: [
        "3023250f82464559c9911c63c67d9f55cf4b7382460c1f3c0e4155b55d18239a",
        "b27e21242f3bd6df490776e26466ade4e6b1845c07a12eff43b5ba1862788e52",
        "8081134e6b0692628719026f0578a0182454757cfa02f5d240f374b64e52e487",
        "3d7ba9cf62c1bf977a3063eb6e9eaa8abc5a8622e7647dc7bfdb4cf27cf1c957"
      ]
    },
    {
      id: 2,
      name: "VIKUS",
      member_ids: [1,2,4,24],
      oauth_application_uids: [
        "b27e21242f3bd6df490776e26466ade4e6b1845c07a12eff43b5ba1862788e52",
        "8081134e6b0692628719026f0578a0182454757cfa02f5d240f374b64e52e487"
      ]
    }
  ],
  user_accessors: [
    {
      username: "nebukadnezzar",
      id: 1,
      email: "",
      display_name: "Nebukadnezzar I",
      image_thumb_50: "http://localhost:3000/uploads/store/d577ae9672995d485974168ffc51e5be.jpg"
    }
  ]
}

Further routes for user authorization

GET    /oauth/authorize/:code
GET    /oauth/authorize
POST   /oauth/authorize
DELETE /oauth/authorize
POST   /oauth/token
POST   /oauth/revoke
GET    /applications
POST   /applications
GET    /applications/:id
PATCH  /applications/:id
PUT    /applications/:id
DELETE /applications/:id

GET /oauth/authorize/:code

Provides a page with the authorization code.

curl command

curl http://babili.toboter.de/oauth/authorize/fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0

command output

HTML page that includes the following content:

<h3>Authorization code:</h3>
<code id="authorization_code">fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0</code>

POST /oauth/authorize

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 command

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

command output

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>

DELETE /oauth/authorize

Revoke OAuth authorization, deletes the access token.

curl command

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

command output

Redirect to redirect_uri

POST /oauth/token

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 command, authorization code grant

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

command output

{"access_token":"dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781","token_type":"bearer","expires_in":7200,"refresh_token":"76ba4c5c75c96f6087f58a4de10be6c00b29ea1ddc3b2022ee2016d1363e3a7c","scope":"public"}

curl command, password grant

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

command output

{"access_token":"0ddb922452c983a70566e30dce16e2017db335103e35d783874c448862a78168",
"token_type":"bearer",
"expires_in":7200,
"refresh_token":"f2188c4165d912524e04c6496d10f06803cc08ed50271a0b0a73061e3ac1c06c",
"scope":"public"}

curl command, refresh token grant

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

command output

{"access_token":"ad0b5847cb7d254f1e2ff1910275fe9dcb95345c9d54502d156fe35a37b93e80",
"token_type":"bearer",
"expires_in":30,
"refresh_token":"cc38f78a5b8abe8ee81cdf25b1ca74c3fa10c3da2309de5ac37fde00cbcf2815",
"scope":"public"}

failed response command output (invalid username, password, or code)

{"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."}

POST /oauth/revoke

Post here with client credentials (in basic auth or in params client_id and client_secret) to revoke an access/refresh token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC (RFC 7009).

curl command, token revoke with client credentials in params

curl -F client_id=9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f \
-F client_secret=d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2 \
-F token=dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781 \
-X POST http://localhost:3000/oauth/revoke

command output

{}

curl command, token revoke with client credentials in basic auth

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 token=dbaf9757982a9e738f05d249b7b5b4a266b3a139049317c4909f2f263572c781 \
-u '9b36d8c0db59eff5038aea7a417d73e69aea75b41aac771816d2ef1b3109cc2f:d6ea27703957b69939b8104ed4524595e210cd2e79af587744a7eb6e58f5b3d2' \
-X POST http://localhost:3000/oauth/revoke

command output

{}

GET /oauth/token/info

Shows details about the token used for authentication

curl command

curl -H "Authorization: Bearer 53cff8f4a549beb1c38704158b0f6608a2382f094b6947ecc35c2eed4146a17c" \
     localhost:3000/oauth/token/info

command output

{"resource_owner_id":1,
"scopes":[],
"expires_in_seconds":7178,
"application":{"uid":null},
"created_at":1440460991}

token not found, command output

{"error":"invalid_request",
"error_description":"The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed."}

POST /oauth/revoke

Revokes the given token, requires authentication

curl command

curl -F token=53cff8f4a549beb1c38704158b0f6608a2382f094b6947ecc35c2eed4146a17c \
 -H "Authorization: Bearer 53cff8f4a549beb1c38704158b0f6608a2382f094b6947ecc35c2eed4146a17c" \
 -X POST localhost:3000/oauth/revoke

result

Always returns 200 OK, even if token doesn't exist or has already been revoked.