OAuth 2.0 Example

Introduction:

DRACOON API access authorization can in addition to the X-Sds-Auth-Token also be done via an OAuth Access Token.

For information about OAuth, see: https://oauth.net/2, https://tools.ietf.org/html/rfc6749

Before you can start to use OAuth you have to create an OAuth client. Article OAuth 2.0 Client Registration describes how to create an OAuth client.

OAuth Endpoints:

Example:

The following example uses the Authorization Code grant. (See: https://tools.ietf.org/html/rfc6749#section-4.1)

1. Create/build authorization URL

Following parameters must be added to the authorization URL:

- response_type=code

- client_id=example-client (Your client ID.)

- redirect_uri=https://app.example.com/oauth/cb (Your registered redirect URI.)

- state=xyz (A string which you can use to map authorization request and callback.)

Result:

https://dracoon.team/oauth/authorize?response_type=code&
client_id=example-client&
state=xyz &
redirect_uri=https%3A%2F%2Fapp%2Eexample%2Ecom%2Foauth%2Fcb

2. Open authorization URL in browser

To allow a user to authorize your app, he/she must be send to the authorization server. (The URL should be opened in the system's browser. A integrated web view is not recommended.)

3. Receive authorization callback and extract code

After the user has authorized your app, you receive a callback to the registered redirect URI which contains the authorization code. It might look like:

- Web App: https://app.example.com/oauth/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

(- Mobile App: app-example://oauth/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz)

4. Exchange code for tokens

To get an access and refresh token you must use the token endpoint.

Request:

(You must use your client ID and client secret to authenticate. See: https://en.wikipedia.org/wiki/Basic_access_authentication)

POST /oauth/token HTTP/1.1
Host: dracoon.team
Authorization: Basic ZXhhbXBsZS1jbGllbnQ6ZXhhbXBsZS1zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=example-client&
code=SplxlOBeZQQYbYS6WxSbIA&
redirect_uri=https%3A%2F%2Fapp%2Eexample%2Ecom%2Foauth%2Fcb

Response:

Status: 200 OK
Content-Type: application/json

{
    "access_token": "b1b735fe-4767-3299-9b37-594f512cf553",
    "token_type": "bearer",
    "refresh_token": "2f3a47a6-b5f4-4761-e99f-badf7011425b",
    "expires_in": 3599,
    "scope": "all"
}

5. Call API

After you have received the access token you can call a API. The access token must be supplied in the authorization header.

Request:

GET /api/v4/nodes HTTP/1.1
Host: dracoon.team
Authorization: Bearer b1b735fe-4767-3299-9b37-594f512cf553