-
Notifications
You must be signed in to change notification settings - Fork 208
Please take into account that this article is a draft and is not yet finished
oauthd's API is composed of two main parts, the base features API, and the auth API. These are extended by endpoints brought by plugins and extensions. Each plugin brings its own set of endpoints.
The basic API allows you to manipulate the core features of oauthd, apps, providers, etc, using your admin account (if you are using the default admin auth plugin).
You need to be authenticated to use some of the following endpoints. The authentication process differs according to the used authentication plugin. The default authentication plugin (admin auth plugin) authentication process is explained in the second part of this WIKI section.
A middleware request handler, env.middlewares.auth.needed, usually created by auth plugins,
is added in several of the API's endpoints. This middleware requires some form of authentication
in the request.
In the default admin auth plugin, your request must contain the header Authentication
containing Bearer [your_token]. The token can be obtained by using the /signin endpoint
with a JSON body containing the name and pass fields (your name and password).
The following endpoints are used in the default oauthd front plugin. You can create your own front plugin using these endpoints.
POST /api/apps
This endpoint allows you to create an app.
Headers
-
Content-Type:application/json
Payload
The payload must be well formatted JSON.
-
name: string The name of your app. Must match/^.{3,50}$/(required) -
domains: array The list of authorized domains (optional)
Success response
The endpoint will respond with an HTTP 200 code if all went well.
The endpoint returns a JSON document representing the created app as payload. These are the returned fields:
-
id: integer The id of your app -
name: string The name of your app -
key: string The public key of your app
Error responses
-
Bad parameters format: Some parameters were missing or wrong
GET /api/apps/:key
This endpoint allows you to retrieve an app's information.
Url parameters
-
:key: string The public key of your app. Must match/^[a-zA-Z0-9\-_]{23,27}$/
Success response
The endpoint will respond with an HTTP 200 code if all went well.
The endpoint returns a JSON document representing the app as payload. These are the returned fields:
-
id: integer The app's id -
name: string The app's name -
key: string The app's public key -
secret: string The app's secret key -
date: timestamp The app's creation date -
owner: string The app owner's id (adminif using the default admin auth plugin)
Error responses
-
Bad parameters format: Some parameters were missing or wrong
POST /api/apps/:key
This endpoint allows you to update an app's information.
Url parameters
-
:key: string The public key of your app. Must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist.
Headers
-
Content-Type: must beapplication/json
Payload
The payload must be a well formatted JSON document, containing the following fields:
-
name: string The name you want your app to have, must match/^.{3,50}$/(optional) -
domains: array The list of domains of your app (optional)
Success response
The endpoint will respond with an HTTP 200 code if all went well.
Error responses
-
Bad parameters format: Some parameters were missing or wrong
DELETE /api/apps/:key
This endpoint allows you to delete an app.
Url parameters
-
:key: string The public key of the app you want to delete, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist.
Success response
The endpoint will respond with an HTTP 200 code if all went well.
Error responses
-
Bad parameters format: Some parameters were missing or wrong
POST /api/apps/:key/reset
This endpoint allows you to reset an app's public and secret keys.
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist.
Success response
The endpoint responds with an HTTP 200 code if all went well.
The response's payload is a JSON document containing the following fields:
-
key: string The app's new public key -
secret: string The app's new secret key
Error responses
-
Bad parameters format: Some parameters were missing or wrong
GET /api/apps/:key/domains
This endpoint allows you to retrieve an app's authorized domains list.
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist.
Success response
The endpoint responds with an HTTP 200 code if all went well.
The response's payload is a JSON document containing an array of all the app's authorized domains.
Error responses
-
Bad parameters format: Some parameters were missing or wrong
POST /api/apps/:key/domains
This endpoint allows you to update an app's authorized domains list.
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist.
Payload
The request payload must be a well formatted JSON document containing an array of strings representing each of the app's authorized domains.
Success response
The endpoint responds with an HTTP 200 code if all went well.
The response's payload is a JSON document containing an array of all the app's authorized domains.
Error responses
-
Bad parameters format: Some parameters were missing or wrong
POST /api/apps/:key/domains/:domain
This endpoint allows you to add a domain to the app's authorized domains list.
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist. -
domain: string The domain to add, URL encoded
Success response
The endpoint responds with an HTTP 200 code if all went well.
Error responses
-
Bad parameters format: Some parameters were missing or wrong
DELETE /api/apps/:key/domains/:domain
This endpoint allows you to remove a domain to the app's authorized domains list.
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist. -
domain: string The domain to remove, URL encoded. The domain must be in the current app's authorized list
Success response
The endpoint responds with an HTTP 200 code if all went well.
Error responses
-
Bad parameters format: Some parameters were missing or wrong
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist.
Success response
The endpoint responds with an HTTP 200 code if all went well.
Error responses
-
Bad parameters format: Some parameters were missing or wrong
GET /api/apps/:key/keysets
This endpoint allows you to retrieve the list of activated providers for a given app.
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist.
Success response
The endpoint responds with an HTTP 200 code if all went well.
The response is a JSON document containing the list of all the activated providers.
Example:
[
"facebook",
"google",
"twitter"
]Error responses
-
Bad parameters format: Some parameters were missing or wrong
GET /api/apps/:key/keysets/:provider
This endpoint allows you to get the key set for a given provider and a given app. A keyset is a set of values corresponding to fields required by the provider. The set contains client_id and client_secret for most providers.
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist. -
:provider: string The provider
Success response
The endpoint responds with an HTTP 200 code if all went well.
The response's payload is a JSON document containing the keyset.
{
"parameters": {
// fields defined by the provider for an app
},
// The mode of the app containing this provider
// token means client side use (client side SDKs and APIs)
// code means server side use (server side SDKs and APIs, allows refresh tokens)
// both allows the two
"response_type": "token|code|both"
}Error responses
-
Bad parameters format: Some parameters were missing or wrong
POST /api/apps/:key/keysets/:provider
This endpoint allows you to update the keyset for a given provider and a given app. The set contains client_id and client_secret for most providers.
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist. -
:provider: string The provider
Request payload
The request payload must be a well formatted JSON document of the following form:
{
"parameters": {
// fields defined by the provider for an app
}
}Success response
The endpoint responds with an HTTP 200 code if all went well.
Error responses
-
Bad parameters format: Some parameters were missing or wrong
DELETE /api/apps/:key/keysets/:provider
This endpoint allows you to delete the keyset for a given provider and a given app. The set contains client_id and client_secret for most providers.
Url parameters
-
:key: string The public key of the app, must match/^[a-zA-Z0-9\-_]{23,27}$/. The app must exist. -
:provider: string The provider
Success response
The endpoint responds with an HTTP 200 code if all went well.
Error responses
-
Bad parameters format: Some parameters were missing or wrong
GET /api/providers
This endpoint allows you to retrieve the complete list of available providers.
Success response
The endpoint responds with an HTTP 200 code if all went well.
The response's payload is a JSON document containing an array of providers, of the following form:
[
//...
{
"provider": "provider_name",
"name": "provider_name_pretty"
},
//...
]
GET /api/providers/:provider
This endpoint allows you to retrieve the configuration of a given provider.
URL parameters
-
:provider: string The provider name. The provider must exist in oauthd.
Success response
The endpoint responds with an HTTP 200 code if all went well.
The response's payload is a JSON document representing the provider's configuration. The returned fields depend on the provider and their compliance to the OAuth protocol.
GET /api/providers/:provider/settings
This endpoint allows you to retrieve information about the provider's configuration on their side, with, for example, links to screenshots.
Success response
The endpoint responds with an HTTP 200 code if all went well.
The response's payload is a JSON document containing the information.
GET /api/providers/:provider/logo
This endpoint returns an image of the provider's logo.
The Token API endpoints allow you to connect your user to a provider though the REST API.
HTTP GET redirection to /auth/:provider
When you redirect a user to this endpoint, this one is redirected to the provider's authorization dialog.
You have two ways to receive the authorization results:
- by using a redirect_uri, the results are received in the url fragments
- by using a cross-domain window message
This endpoint accepts the following GET parameters:
| Field | Description |
|---|---|
| k |
Required The oauth.io app's public key |
| opts |
Optional JSON encoded additional options |
| redirect_type |
Optional Set to server if you use a server-side flow |
| redirect_uri |
Optional If provided, the result is sent in the url fragment of this redirection |
To avoid CSRF vulnerability, you should add a generated token in the opts object. To do so, add a state_type field set to "client" and a state field that contains a random string / hash. You will get the state back in the response object, and you must check that it is the same state that you sent.
If you set the redirect_uri parameter, you can receive the result from the url-encoded json data in the url fragment oauthio parameter.
e.g.
https://mydomain.com/oauth/callback#oauthio=%7B%22access_token%22%3D%22xxxxxx%22...
If you set the redirect_type parameter to server, the result in sent in the url query instead of fragment. With this option, you should check that your oauthd app is set to "server-side authentication" ("prevent front-end auth" on oauth.io) so you can receive a code instead of the access token directly. This way, only your server can get the access token:
{
"status":"success",
"data": {
"code":"Bqr_QxSl3l_mnuBQDEMizl_bkt8"
},
"state":"...",
"provider":"facebook"
}
You must redirect the user or remove the url fragment or query as soon as you receive the results.
To exchange a code for an access token, you must call
POST /auth/access_token
| Field | Description |
|---|---|
| code |
Required The code to exchange for an access token |
| key |
Required The oauthd app's public key |
| secret |
Required The oauthd app's secret key |
Without using the redirect_uri parameter, you must catch the result sent to the parent window:
if (window.addEventListener) {
window.addEventListener('message', getmessage, false);
} else if (window.attachEvent) {
window.attachEvent('onmessage', getmessage);
}To allow IE to use a cross-domain cross-window messaging, you must additionally include an hidden iframe to /auth/iframe
var frm = document.createElement("iframe");
frm.src = "https://oauth.io/auth/iframe?d=mydomain.com";
frm.width = 0;
frm.height = 0;
frm.frameBorder = 0;
frm.style.visibility = "hidden";
document.body.appendChild(frm);If you are using a chrome extension, chrome.runtime.onMessageExternal.addListener will be used and you must use chrome.runtime.onMessageExternal.addListener to receive the message.
In any case, you MUST check the event origin to be your oauthd domain. e.g. https://mydomain.com
| Field | Description | Type | Example value |
|---|---|---|---|
| access_token | OAuth 2 -- The authorization key to access the OAuth2 API | string | CAAHv...aAWy |
| oauth_token | OAuth 1 -- The authorization key to access the OAuth1 API | string | XVQpX...WR0K |
| oauth_token_secret | OAuth 1 -- The second authorization key to access OAuth1 API | string | PHQD2...V7xw |
| expires_in |
Optional depending the provider -- The expiration of the access_token
|
integer | 5184000 |
| code | Client side only -- The code to be exchanged against the access token server side authorization | string | XsrpW...leE3 |
| refresh_token | Optional -- The refresh token is used to refresh the access_token to extend the expiration. | string | Tgfgso |
| provider | The provider your user is connected with. | string | |
| state | If you set the state_typefield in the additional options to "client", this will send back the statefield |
string | OSJC...d5SG |
You can also receive additionals data relative to the provider, like id_token (for openid), email...
If the provider you use does not allow cross domain API requests and you do not want to call it from server-side, this endpoint allow you to use the oauthd proxy to authorize and make the requests.
GET | POST | PUT | DELETE | PATCH /request/:provider/:url
| Field | Description |
|---|---|
| provider | The provider's name (e.g. "facebook") |
| url | The api request's url, can be relative to the main api domain (e.g api.facebook.com) or absolute. This url must be urlencoded. |
You must include the oauthio HTTP header inside your request, which is a application/x-www-form-urlencoded hash containing:
| Field | Description |
|---|---|
| k | The public oauthd key of your app. If the http header Origin or Referer is set, this will be checked against your app's whitelist. If none are present, you must accept the "localhost" domain in your OAuthd's app. |
| oauth_token | OAuth1 public token. |
| oauth_secret_token | OAuth1 secret token. |
| access_token | OAuth2 token. |
| oauthv (optional) | when a provider supports both OAuth1 and OAuth2, this can be set to "1" or "2" to desambiguate the version of OAuth to use. |
##User data API
This API allows you to retrieve your user's data in a unified way. This means you don't have to make a bridge between APIs to retrieve user's info, all fields sent are unified and described here. Filters can be added to retrieve a subset of these unified fields.
GET /auth/:provider/me
You must authorize the request with the same oauthio HTTP header than the Request API.
| Field | Description | Type | Example value |
|---|---|---|---|
| id | The user id -- This id is unique for a provider | string | "1234" |
| name | The user's name | string | John Doe |
| firstname | The user's firstname | string | John |
| lastname | The user's lastname | string | Doe |
| alias | The user's alias (or login) | string | john87 |
| The user's email address | string | [email protected] | |
| birthdate | The user's birthday | Object | {day: 27, month: 11, year: 1987} |
| gender | The user's gender. 0: male; 1: female | integer | 0 |
| location | The user's last location | string | San Francisco |
| local | The user's local | string | FR |
| company | The user's company | string | Webshell |
| occupation | The user's job occupation | string | developer |
| raw | The unmodified provider's response with non unified field | Object |
e.g.
{
"id": "1234",
"name": "John Doe",
"firstname": "John",
"lastname": "Doe",
"alias": "john87",
"email": "[email protected]",
"birthdate": {
"day": 27,
"month": 11,
"year": 1987
},
"raw": {
[RAW RESULT]
}
}
TODO