Authentication

Get an access and refresh token

In order to get an access token, you need to have the following data

1. username (the email address of your user)
2. password (the password of your user)
3. the client credentials of your app
   • the client name (e.g. breakout_app)
   • the client secret (e.g. 123456789)
4. The grant type (in this case password). See [OAuth 2 Introduction](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2 for more examples) by DigitalOcean for more details
5. The scope (in order to modify your users data, you need read write access)

In order to get the access and refresh token, you need to do POST yourdomain.org/oauth/token. The client name and client secret need to be transmitted via HTTP Basic Authentication. The username, password, grant_type and scope should be provided via x-www-form-urlencoded body. A full Http Request could look like the following

POST /oauth/token HTTP/1.1
Authorization: Basic BASE64ENCODEDCLIENTCREDENTIALS
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Host: yourdomain.org
Connection: close
Content-Length: 85

username=admin%40break-out.org&password=password&grant_type=password&scope=read+write

As a response you would then get the following Json

{
  "access_token": "YOURACCESSTOKEN",
  "token_type": "bearer",
  "refresh_token": "YOURREFRESHTOKEN",
  "expires_in": 42961,
  "scope": "read write"
}

Use the access token

Accessing protected API endpoints is done by sending the access token in the header of the Http Request. E.g. if one wants to get details about the user to whom an access token belongs to, this can be done via GET yourdomain.org/me/. The full request including the authorization header would look like the following:

GET /me/ HTTP/1.1
Authorization: Bearer YOURACCESSTOKENHERE
Content-Type: application/json
Host: yourdomain.org
Connection: close

Get a new access token with the refresh token

An access token has only a limited time frame in which it is valid. In order to receive a new access token without needing to send the username and password again, the refresh token can be used. The data one needs to provide are the client credentials over Http Basic Auth and the refresh_token=YOURTOKEN and grant_type=refresh_token in a x-www-form-urlencoded body

POST /oauth/token HTTP/1.1
Authorization: Basic BASE64ENCODEDCLIENTCREDENTIALS
Content-Type: application/x-www-form-urlencoded
Host: yourdomain.org
Connection: close
Content-Length: 75

refresh_token=YOURREFRESHTOKEN&grant_type=refresh_token