API

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

##Base features API

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

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). ###Available endpoints

The following endpoints are used in the default oauthd front plugin. You can create your own front plugin using these endpoints.

####App Creation 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

####App information retrieval 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

####App information update 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

####App deletion 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

####App keys reset 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

####App domains list retrieval 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

####App domains list update 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

####App domain add 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

####App domain deletion 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

####App keysets list retrieval (activated providers) 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

####App keyset retrieval for given provider 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

####App keyset update for given provider 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

####App keyset deletion for given provider 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

####App backend retrieval GET /api/apps/:key/backend

This endpoint allows you to get the backend of an app. If The backend is set, it means that the app is to be used server-side.

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 of the following form:

{
    "name": "node|php",
    "value":{
        // Any value set for a given backend
    }
}

Error responses

Bad parameters format: Some parameters were missing or wrong

####App mode set POST /api/apps/:key/backend/:backend

This endpoint allows you to set the backend of an app. If The backend is set, it means that the app is to be used server-side.

Url parameters

:key: string The public key of the app, must match /^[a-zA-Z0-9\-_]{23,27}$/. The app must exist.
:backend: string The backend you want to use (node, php, go or api)

Payload

The payload must be a well formed JSON document of the following form:

{
    "name": "node|php|go|api",
    "value":{
        // Any value required by other features
    }
}

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

####App mode reset DELETE /api/apps/:key/backend

This endpoint allows you to remove the backend of an app. Once the backend is removed, the app will work client

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

####Full providers list retrieval 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"
    },
    //...
]

####Provider config retrieval 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.

####Provider settings retrieval 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.

####Provider logo retrieval GET /api/providers/:provider/logo

This endpoint returns an image of the provider's logo.

##Auth API

#Default plugins APIs ##Admin Auth

##Request API ##Me API ##Default Front API

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API

Navigation

Clone this wiki locally