Wordapp API

 

Authenticating with OAuth 2.0

At Wordapp, we value the integrity and security of our members’ data above all else. In order for your applications to access Wordapp member data and/or act on their behalf, they must be authenticated. To make this process as easy as possible, Wordapp relies on the industry standard OAuth 2.0 protocol for granting access.

There are two methods to create access token such as using username & password or using Wordapp application.

1. Creating an access token using username & password

Wordapp users have a username and password. A user can easily hit the following request so as to create an access token.

 

Parameter Description Required
grant_type
Value MUST be set to "password".
Yes
username User’s username or e-mail registered at Wordapp. Yes
password User’s password registered at Wordapp Yes
Sample Call
POST /oauth/token HTTP/1.1
Host: app.wordapp.io
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=mehmet&password=password
Sample Response
{
  "access_token": "f292d8797bde64071bb1a3177431b57f992932f6f2fa086377bc27b17744b859",
  "token_type": "bearer",
  "expires_in": 31555719,
  "refresh_token": "0fcbcf9198c82c69db936b397903bb992c04a2ea0167799288101718d3f58266",
  "scope": "public",
  "created_at": 1476891745
}

2. Creating an access token using Wordapp Application

      1. Configuring your Wordapp application

If you have not already done so, create an application. If you have an existing application, select it to modify its settings.

To prevent fraudulent transactions during the authentication process, we will only communicate with URLs that you have identified as trusted endpoints.  Ensure the “OAuth 2.0 Redirect URLs” field for your application contains a valid callback URL to your server that is listening to complete your portion of the authentication workflow.

 

Please note that:

 

 

 

       

 Once you save your configuration, your application will be assigned a unique “Application ID”  and “Client Secret” value.  Make note of these values — you will need to integrate them into the configuration files or the actual code of your application, for example:

 

Important!

 

At the risk of your own application’s security, DO NOT share your Client Secret value with anyone! This includes posting it in support forums for help with your application.

      2. Request an Authorization Code

Once your application is properly configured, it’s time to request an authorization code.  The authorization code is not the final token that you use to make calls to Wordapp with.  It is used in the next step of the OAuth 2.0 flow to exchange for an actual access token.  This is an important step because it provides assurance directly from Wordapp to the user that permission is being granted to the correct application, with the agreed-upon access to the member’s Wordapp profile.

 

Redirecting the user

To request an authorization code, you must direct the user’s browser to Wordapp’s OAuth 2.0 authorization endpoint.  Once the request is made, one of the following two situations will occur:

  • If the user has not previously accepted the application’s permission request, or the grant has expired or been manually revoked by the user, the browser will be redirected to Wordapp’s authorization screen.  When the user completes the authorization process, the browser is redirected to the URL provided in the redirect_uri query parameter.
  • If there is a valid existing permission grant from the user, the authorization screen is by-passed and the user is immediately redirected to the URL provided in the redirect_uri query parameter.

Note that if you ever change the scope permissions that your application requires, your users will have to re-authenticate to ensure that they have explicitly granted your application all of the permissions that it requests on their behalf.

 

 

Parameter Description Required
response_type
Value MUST be set to "code"
Yes
client_id The “API Key” value generated when you registered your application. Yes
redirect_uri

The URI your users will be sent back to after authorization.  This value must match one of the defined OAuth 2.0 Redirect URLs in your application configuration.

e.g. https://www.example.com/auth/wordapp

Yes
Sample Call
https://app.wordapp.io/oauth/authorize?response_type=code&client_id=123456789&redirect_uri=https%3A%2F%2Fwww.example.com%2Fauth%2Fwordapp

The User Experience

Once redirected, the user will be presented with Wordapp’s authentication dialog box. This identifies your application as well as outlines the particular member permissions that your application has requested. If desired, the logo and application name can be changed in your application configuration.

 

Application is Approved

By providing valid Wordapp credentials and clicking on the “Authorize” button, the user approves your application’s request to access their member data and interact with Wordapp on their behalf. This approval instructs Wordapp to redirect the user back to the callback URL that you defined in your redirect_uri parameter.

Attached to the redirect_uri will be important URL arguments that you need to read from the request:

code — The OAuth 2.0 authorization code.

 

The code is a value that you will exchange with Wordapp for an actual OAuth 2.0 access token in the next step of the authentcation process.  For security reasons, the authorization code has a very short lifespan and must be used within moments of receiving it – ie. before it expires, and you need to repeat all of the previous steps to request another.

Application is Rejected

If the user choses to cancel, or the request fails for any other reason, their client will be redirected back to your redirect_uri callback URL with the following additional query parameters appended:

error – A code indicating the type of error. One available string is:

    • access_denied – The user refused to authorize permissions request from your application.

error_description – A URL-encoded textual description that summarizes the error.

      3. Exchange Authorization Code for an Access Token

The final step towards obtaining an Access Token is for your application to ask for one using the Authorization Code it just acquired. This is done by making the following “x-www-form-urlencoded” HTTP POST request:

 

Parameter Description Required
grant_type The value of this field should always be: authorization_code Yes
code The authorization code you received from Step 2.
Yes
redirect_uri

The same ‘redirect_uri’ value that you passed in the previous step.

Yes
client_id The “API Key” value generated Step 1. Yes
client_secret The “Secret Key” value generated in Step 1. Yes

 

Sample Call
POST /oauth/token HTTP/1.1
Host: app.wordapp.io
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=84dafee0b04&redirect_uri=https%3A%2F%2Fwww.myapp.com%2Fauth%2Fwordapp&client_id=4d8kfd3545re&client_secret=9cbad8b8f
Sample Response
{
  "access_token": "f292d8797bde64071bb1a3177431b57f992932f6f2fa086377bc27b17744b859",
  "token_type": "bearer",
  "expires_in": 31555719,
  "refresh_token": "0fcbcf9198c82c69db936b397903bb992c04a2ea0167799288101718d3f58266",
  "scope": "public",
  "created_at": 1476891745
}

4. Creating an access token using client_id & client_secret

In order to create an access token with client_id & client_secret you should have an application and it is explained in detail in “Creating an access token using wordapp application” section that how to create an application. So the request should be like the following:

Parameter Description Required
grant_type The value of this field should always be: client_credentials Yes
client_id The “API Key” value generated Step 1. Yes
client_secret The “Secret Key” value generated in Step 1. Yes
Sample Call
POST /oauth/token HTTP/1.1
Host: app.wordapp.io
Content-Type: application/x-www-form-urlencoded
client_id=4d8ab515a82b14a718&client_secret=9cbad8b8f4df19cd&grant_type=client_credentials
Sample Response
{
  "access_token": "f292d8797bde64071bb1a3177431b57f992932f6f2fa086377bc27b17744b859",
  "token_type": "bearer",
  "expires_in": 31555719,
  "scope": "public",
  "created_at": 1476891745
}

4. Refresh your access token

To protect our member’s data, Wordapp does not generate excessively long-lived access tokens. Once the token is generated it is expired in 2 hours. You should ensure your application is built to handle refreshing user tokens before they expire, to avoid having to unnecessarily send your users through the authorization process to re-gain access to their Wordapp profile.

Refreshing a token:

After getting a token from Wordapp, in the payload there are “refresh_token” and “expires_in” keys. “expires_in” key’s value is second and defines how many seconds after the token will expire. The “refresh_token” key is a token in order to revoke the current token and create another fresh token.

 

Parameter Description Required
grant_type The value of this field should always be: refresh_token Yes
refresh_token The refresh_token key in token payload which is produced by the server Yes
Sample Call
POST /oauth/token HTTP/1.1
Host: app.wordapp.io
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=9c91e64d39ef1e9dd67d9
Sample Response
{
  "access_token": "f292d8797bde64071bb1a3177431b57f992932f6f2fa086377bc27b17744b859",
  "token_type": "bearer",
  "expires_in": 31555719,
  "refresh_token": "0fcbcf9198c82c69db936b397903bb992c04a2ea0167799288101718d3f58266",
  "scope": "public",
  "created_at": 1476891745
}

5. Revoking access token

In order to revoke access token you should include “Authorization” header in addition to “token” post parameter in you HTTP call. Revoking can be done with following example.

 

Parameter Description Required
token access token you get from wordapp Yes
Sample Call
POST /oauth/revoke HTTP/1.1
Host: app.wordapp.io
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer ebecf0c60cdc38888726cab
token=ebecf0c60cdc38888726cab

6. Make authenticated requests

Once you’ve obtained an Access Token, you can start making authenticated API requests on behalf of the user. This is accomplished by including an “Authorization”  and “X-Api-Version” headers in your HTTP call to Wordapp’s API.  Here is a sample HTTP request including the header value that includes the token:

Sample Call
GET /api/me HTTP/1.1
Host: app.wordapp.io
Authorization: Bearer 2b2efb07761f62c6f07de8cec5978b8c9b4f2a2cb439564c005a6fa2f305b300
X-Api-Version: application/vnd.wordapp-v1+json

 

Invalid Tokens

If you make an API call using an invalid token, you will receive a “401 Unauthorized” response back from the server.  A token could be invalid and in need of regeneration because:

  • It has expired.
  • The user has revoked the permission they initially granted to your application.
  • You have changed the member permissions (scope) your application is requesting.
  • A subsequent OAuth2 flow that generated a new access token. The previous token will be invalidated.

Since a predictable expiry time is not the only contributing factor to token invalidation, it is very important that you code your applications to properly handle an encounter with a 401 error by redirecting the user back to the start of the authorization workflow.