Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
481 lines (342 sloc) 16.6 KB
FORMAT: 1A
HOST: https://syrup.keboola.com/oauth-v2
# OAuth Manager
**DEPRECATED**
Use https://oauthapi3.docs.apiary.io/.
Create and manage Credentials for API resources utilizing OAuth 1.0 and 2.0
This API aims to handle all OAuth authorization processes. This list of supported APIs is managed by KBC Dev team
The authorization process can be initiated manually to retrieve OAuth tokens for development/testing purposes.
Using a `POST` request with `token` and `id` will store the result in the application database, encrypted by Keboola Docker application with matching `componentId`. The component must support encryption. After storing the result, the application redirects to `HTTP_REFERRER`, which can be overriden by using `returnUrl` parameter in the POST request.
The `GET` request for "manual" authentication returns the raw contents of `#data`, but does **not** store the result.
The `X-KBC-ManageApiToken` must have `oauth:manage` scope.
## Callback URL
The callback URL for the API is generated using the `componentId`, into the following URL: `https://syrup.keboola.com/oauth-v2/authorize/{componentId}/callback`
## TODO
- scope is missing
# Group Authorize
## Generate OAuth token for OAuth applications [/authorize/{componentId}{?token,id,authorizedFor,returnUrl,userData}]
If the component uses `%%subdomain%%` in the URL, the authorize request **must** be sent using a form POST request and contain `userData` field.
### Get a TEST token in browser [GET]
+ Parameters
+ componentId: `wr-dropbox` (string, required) - Identifier of the KBC component
+ Response 201 (application/json)
{
"access_token": "dsjioafhoiy832yt598y7895y",
"refresh_token": "kf98v0894u8j580jy8902xyjciurewc",
"token_type": "Bearer"
}
### Generate token from a web form/UI [POST]
+ Parameters
+ componentId: `yourApp` (required, string) - Identifier of the KBC component
+ token: `305-78945-rg48re4g86g48gwgr48e6` (required, string) - Your KBC Token
+ id: `main` (required, string) - Credentials configuration identifier to be saved with the result
+ authorizedFor: `Someone's account` (optional, string) - Credentials description (eg. account name)
+ returnUrl: `http://back.to.ui` (optional, string) - Override the HTTP Referrer
+ userData: `{"subdomain": "keboola"}` (optional, string) - Required if the API uses a `%%subdomain%%` part in the URL
+ Request (multipart/form-data; boundary=----WebKitFormBoundaryC5GD12ZfR1D8yZIt)
+ Body
------WebKitFormBoundaryC5GD12ZfR1D8yZIt
Content-Disposition: form-data; name="token"
305-78954-d54f6ew4f84ew6f48ewq4f684q
------WebKitFormBoundaryC5GD12ZfR1D8yZIt--
------WebKitFormBoundaryC5GD12ZfR1D8yZIt
Content-Disposition: form-data; name="id"
main
------WebKitFormBoundaryC5GD12ZfR1D8yZIt--
------WebKitFormBoundaryC5GD12ZfR1D8yZIt
Content-Disposition: form-data; name="authorizedFor"
Credentials description (eg. account name)
------WebKitFormBoundaryC5GD12ZfR1D8yZIt--
+ Schema
{
"type": "object",
"required": true,
"properties": {
"id": {
"type": "string",
"required": true
},
"token": {
"type": "string",
"required": true
},
"componentId": {
"type": "string",
"required": true
},
"authorizedFor": {
"type": "string",
"required": false
}
}
}
+ Response 302
## Callback [/authorize/{componentId}/callback]
### Handle the callback action [GET]
The response is determined based on the session's stored `referrer` or `returnUrl`. If the initial request to OAuth API is made using a `GET` request, the 200 response with raw data is returned and **not saved to database**. If the request is made from a web form, the 302 redirect is returned and result is saved.
+ Parameters
+ componentId: `yourApp` (required, string) - Identifier of the KBC component
+ Response 200 (application/json)
{
"access_token": "FoB3o4tdgj86Rq1chSO7qjBLv2S9XD7e",
"token_type": "bearer",
"uid": "12345678"
}
+ Response 302
# Group Credentials
## Credentials [/credentials/{componentId}]
### Get Credentials list for the project [GET]
+ Parameters
+ componentId: `yourApp` (required, string) - Identifier of the KBC component
+ Request
+ Headers
Accept: application/json
X-StorageApi-Token: Your-Sapi-Token
+ Response 200 (application/json)
[
{
"authorizedFor": "test",
"id": "main",
"creator": {
"id": "1234",
"description": "me@keboola.com"
},
"created": "2016-01-31 00:13:30"
}
]
### Post Credentials [POST]
Useful when you already have access and refresh token.
Content of *data* attribute in the request body is component specific.
+ Parameters
+ componentId: `yourApp` (required, string) - Identifier of the KBC component
+ Request (application/json)
+ Headers
Accept: application/json
X-StorageApi-Token: Your-Sapi-Token
+ Body
{
"id": "main",
"authorizedFor": "Myself",
"data": {
"access_token": "thisIsAccessToken",
"refresh_token": "thisIsRefreshToken"
}
}
+ Response 201 (application/json)
{
"id": "main",
"authorizedFor": "Myself",
"creator": {
"id": "1234",
"description": "me@keboola.com"
},
"created": "2016-01-31 00:13:30",
"#data": "KBC::ProjectSecure::F2LdyHQB45lJHtf6dZbxzfuhqlplplplpxByYn19OJQ3JLpyoxQcEqovAzipNAd6Kxc0PDe2nP468448648aSN0OzJcE4VovJk7YaX8wrzoS+tURTRFuWVFZZ5gpJjQvezj1iOgm++KOROIHNdfohuiogygiwpOuNgPFzgYeg8RL5CCBAB5zzVr4HmT4/DtVdOV+cJ5miPmuHp93sMQA=",
"oauthVersion": "2.0",
"appKey": "w51u7j30oghe412",
"#appSecret": "KBC::ComponentSecure::/5fEM59+3+59+5+uE/TQPwltR8mp+WNu7kYAJkdTXxkc2UswH0YrnAYRjeGTqGp5hA=="
}
## Credentials detail [/credentials/{componentId}/{id}]
+ Parameters
+ componentId: `yourApp` (required, string) - Identifier of the KBC component
+ id: `myCreds` (required, string) - Identifier of credentials
### Get Credentials [GET]
+ Request (application/json)
+ Headers
Accept: application/json
X-StorageApi-Token: Your-Sapi-Token
+ Response 200 (application/json)
{
"id": "main",
"authorizedFor": "Myself",
"creator": {
"id": "1234",
"description": "me@keboola.com"
},
"created": "2016-01-31 00:13:30",
"#data": "KBC::ProjectSecure::F2LdyHQB45lJHtf6dZbxzfuhqlplplplpxByYn19OJQ3JLpyoxQcEqovAzipNAd6Kxc0PDe2nP468448648aSN0OzJcE4VovJk7YaX8wrzoS+tURTRFuWVFZZ5gpJjQvezj1iOgm++KOROIHNdfohuiogygiwpOuNgPFzgYeg8RL5CCBAB5zzVr4HmT4/DtVdOV+cJ5miPmuHp93sMQA=",
"oauthVersion": "2.0",
"appKey": "w51u7j30oghe412",
"#appSecret": "KBC::ComponentSecure::/5fEM59+3+59+5+uE/TQPwltR8mp+WNu7kYAJkdTXxkc2UswH0YrnAYRjeGTqGp5hA=="
}
### Delete credentials [DELETE]
+ Request
+ Headers
Accept: application/json
X-StorageApi-Token: Your-Sapi-Token
+ Response 204
# Group Manage
## Add/List supported API [/manage]
### Get list of supported APIs [GET]
+ Request
+ Headers
Accept: application/json
X-KBC-ManageApiToken: Manage-token
+ Response 200 (application/json)
[
{
{
"id": "ex-adwords",
"friendly_name": "AdWords Extractor",
"app_key": "377121273700-ee1mrkdknfarq5k74pc7qs2g6upqos05.apps.googleusercontent.com",
"oauth_version": "2.0"
},
{
"id": "ex-dropbox",
"friendly_name": "Dropbox Extractor",
"app_key": "519fh4amnds4sx9",
"oauth_version": "2.0"
},
{
"id": "wr-dropbox",
"friendly_name": "Dropbox Writer",
"app_key": "i60qx79tjxdd6v3",
"oauth_version": "2.0"
}
}
]
### Add new component [POST]
You can use `%%subdomain%%` in the URL (eg `https://%%subdomain%%.api.com/oauth/authorize`), which then **requires** an `userData` json to be sent with the auth request to OAuth API, which has to contain a `subdomain` key (eg `{"subdomain": "keboola"}`).
To add `facebook` api component, set `oauth_version` parameter to `facebook` and provide additional `permissions` parameter(coma separated list of values from https://developers.facebook.com/docs/facebook-login/permissions/) and optional `graph_api_version`(default v2.8, or look here https://developers.facebook.com/docs/apps/changelog). For `facebook` auth parameters `auth_url`, `token_url` and `request_token_url` are not required. Facebook authentication will guide user through authorization proccess to retrieve long-lived access token.
+ Request (application/json)
+ Attributes
+ `component_id`: `wr-dropbox` (string, required) - Identifier of the KBC component
+ `friendly_name`: `Your Application` (string, required) - Name of the application
+ `app_key`: `as1d23f48` (string, required) - Consumer Key / Client ID
+ `app_secret`: `f86q4f6e4f64q6f486q` (string, required) - Consumer secret / Client secret. Stored encrypted
+ `auth_url`: `https://www.dropbox.com/1/oauth2/authorize?response_type=code&client_id=%%app_key%%&redirect_uri=%%redirect_uri%%&state=%%hash%%` (string, required) - Authentication URL. Required for oauth 1.0 and 2.0
For **1.0**, `%%oauth_token%%` is replaced by `oauth_token` retrieved by initial POST to API.
For **2.0**, `%%redirect_uri%%` and `%%app_key%%` are replaced by generated redirect URI (to the OAuth application) and `app_key`.
For **facebook** not required
[1.0 Description](http://oauth.net/core/1.0/#auth_step2)
[2.0 Description](http://tools.ietf.org/html/rfc6749#section-4.1.1)
+ `token_url`: `https://api.dropbox.com/1/oauth2/token` (string, required) - Required for oauth 1.0 and 2.0. Access token url. Used in the last step of OAuth process. For **facebook** not required.
[1.0](http://oauth.net/core/1.0/#auth_step3)
[2.0](https://tools.ietf.org/html/rfc6749#section-3.2)
+ `request_token_url`: `https://api.twitter.com/oauth/request_token` (string, optional) - Required for OAuth 1.0 only
[1.0](http://oauth.net/core/1.0/#auth_step1)
+ `oauth_version`: `2.0` (enum[string], required) - OAuth version
+ Members
+ `1.0` - For OAuth 1.0
+ `2.0` - For OAuth 2.0
+ `facebook` - For Facebook OAuth - retrieves facebook long-lived access token
+ `permissions`: `pages_show_list, manage_pages` (enum[string], optional) - for facebook oauth, a coma separated list of permissions for facebook
+ `graph_api_version`: `v2.8` (enum[string], optional) - for facebook oauth ,version of fb graph api used to authorize an account. Default `v2.8`
+ Headers
Accept: application/json
X-StorageApi-Token: Your-Sapi-Token
X-KBC-ManageApiToken: Manage-token
+ Body
{
"component_id": "wr-dropbox",
"friendly_name": "Dropbox Writer",
"app_key": "yourAppKey",
"app_secret": "yourAppSecret",
"auth_url": "https://www.dropbox.com/1/oauth2/authorize?response_type=code&client_id=%%client_id%%&redirect_uri=%%redirect_uri%%",
"token_url": "https://api.dropbox.com/1/oauth2/token",
"oauth_version": "2.0"
}
+ Schema
{
"type": "object",
"required": true,
"properties": {
"component_id": {
"type": "string",
"required": true
},
"friendly_name": {
"type": "string",
"required": true
},
"app_key": {
"type": "string",
"required": true
},
"app_secret": {
"type": "string",
"required": true
},
"auth_url": {
"type": "string",
"required": true,
"description": "For **1.0**, `%%oauth_token%%` is replaced by `oauth_token` retrieved by initial POST to API. For **2.0**, `%%redirect_uri%%` and `%%client_id%%` are replaced by generated redirect URI (to the OAuth application) and `app_key`."
},
"token_url": {
"type": "string",
"required": true
},
"request_token_url": {
"type": "string",
"required": false,
"description": "Required for OAuth 1.0"
},
"oauth_version": {
"type": "string",
"required": true
},
"permissions": {
"type": "string",
"required": true,
"description": "Required for facebook. A comma separated list of permissions"
},
"graph_api_version": {
"type": "string",
"required": false,
"description": "Optional for facebook. Version of fb graph api used to authorize user an account. Default v2.8"
}
}
}
+ Response 200 (application/json)
{
"status": "created",
"component_id": "wr-dropbox"
}
## Delete/Get/Update API detail [/manage/{componentId}]
### Get API detail [GET]
+ Parameters
+ componentId: `yourApp` (required, string) - Identifier of the KBC component
+ Request
+ Headers
Accept: application/json
X-KBC-ManageApiToken: Manage-token
+ Response 200 (application/json)
{
"component_id": "wr-dropbox",
"friendly_name": "Dropbox Writer",
"app_key": "w51y7j30ovhe412",
"app_secret_docker": "KBC::ComponentSecure::/fiewoqhfhoighuqg64gr426wg4864rc26g4re6g/TQPwltR8mp+FEWFwg6gr6e4gc688g6w42==",
"oauth_version": "2.0"
}
### Update component [PATCH]
This API call supports the same parameters as **Add new component** except for `component_id`, which cannote be changed.
+ Request (application/json)
+ Headers
Accept: application/json
X-StorageApi-Token: Your-Sapi-Token
X-KBC-ManageApiToken: Manage-token
+ Body
{
"friendly_name": "Dropbox Writer",
"app_key": "yourAppKey",
"app_secret": "yourAppSecret",
"auth_url": "https://www.dropbox.com/1/oauth2/authorize?response_type=code&client_id=%%client_id%%&redirect_uri=%%redirect_uri%%",
"token_url": "https://api.dropbox.com/1/oauth2/token",
"oauth_version": "2.0"
}
+ Response 200 (application/json)
{
"component_id": "wr-dropbox",
"friendly_name": "Dropbox Writer",
"app_key": "yourAppKey",
"app_secret_docker": "KBC::ComponentSecure::/fiewoqhfhoighuqg64gr426wg4864rc26g4re6g/TQPwltR8mp+FEWFwg6gr6e4gc688g6w42==",
"oauth_version": "2.0"
}
### Delete component [DELETE]
+ Parameters
+ componentId: `yourApp` (required, string) - Identifier of the KBC component
+ Request
+ Headers
Accept: application/json
X-KBC-ManageApiToken: Manage-token
+ Response 204