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 (admin if 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 be application/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:

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

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

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

You must include the oauthio HTTP header inside your request, which is a application/x-www-form-urlencoded hash containing:

##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.

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