Authorizing OAuth Apps

Learn how to enable other users to authorize your OAuth App.

TextMaster's OAuth implementation supports the standard Authorization Code Grant.

See the skip authorization section if you want to skip authorizing your app in the standard way, such as when testing your app, you can use our special callback url.

To authorize your OAuth app, consider which authorization flow best fits your app:

• Web Application Flow: Used to authorize users for standard OAuth apps that run in the browser. (The implicit grant type is not supported)

Web Application Flow

The web application flow to authorize users for your app is:

1. Users are redirected to request their TextMaster identity

2. Users are redirected back to your site by TextMaster

3. Your app accesses the API with the user's access token

Request a user's TextMaster identity

Use the following query to request user's TextMaster identity. User will have to be signed in to authorize your app.

Request a user's TextMaster identity

GET https://app.textmaster.com/oauth/authorize

Query Parameters

Name	Type	Description
client_id*	String	The client ID you received from TextMaster when you registered your app.
redirect_uri*	String	The callback URL that is configured in your registered app.
scope*	String	A space-delimited list of scopes.
response_type*	String	Value must be code (required by the OAuth specification).

200: OK

{
    // Response
}

curl -G https://app.textmaster.com/oauth/authorize \
  -d 'client_id=bd5f986c3e0ca8e3c8f5e9be837631ec1f5003' \
  -d 'redirect_uri=https://example.com' \
  -d 'response_type=code' \
  -d 'scope=user:read user:email'

Users are redirected back to your site by TextMaster

If the user accepts your request, TextMaster redirects back to your site with a temporary code in a code parameter. The temporary code will expire after 10 minutes.

Exchange this code for an access token:

Exchange an OAuth code for a user's access token

POST https://app.textmaster.com/oauth/token

Query Parameters

Name	Type	Description
client_id*	String	The client ID you received from TextMaster when you registered your app.
client_secret*	String	The client secret you received from TextMaster when you registered your app.
grant_type*	String	Value must be authorization_code (required by the OAuth specification).
redirect_uri	String	The same callback URL as sent in step 1.
code*	String	The code you received as a response to step 1.

200: OK

{
  "access_token":"8129442026644ebe93039fecafd79cf776b65",
  "token_type":"Bearer",
  "expires_in":28800,
  "refresh_token":"ce93ba212d2ef6d7a350ba52069839b13882332",
  "scope":"public",
  "created_at":1605191853
}

curl https://app.textmaster.com/oauth/token \
  -F code="80972c05d9012231c493458ed9b98d8d770242d1ceb81895d094b519315b9a51" \
  -F grant_type="authorization_code" \
  -F redirect_uri="https://example.com" \
  -F client_id="bd5f986c3e0ca8e3c8f5e9be837631ec1f5003" \
  -F client_secret="4d556ed945c0735d26663694b24bf0589b"

The response includes two tokens:

• An access_token which is used to access the API on behalf of a user

• A refresh_token which is used to get a new access token when it has expired

Tips: Access token expires after 8 hours. For more information about refresh tokens, see Refreshing access tokens.

Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user.

Authorization: Bearer ACCESS-TOKEN
GET https://api.textmaster.com/v1/clients/users/me

For example, by setting the Authorization header like this:

Get user informations referenced by given access token

GET https://api.textmaster.com/v1/clients/users/me

Headers

Name	Type	Description
Accept*	String	application/json
Authorization	String	Bearer ACCESS-TOKEN

Skip authorization for testing purposes

If you want to skip authorizing your app in the standard way, for example when testing your app, you can register it with the following value as callback URL: urn:ietf:wg:oauth:2.0:oob.

Tips: Use urn:ietf:wg:oauth:2.0:oob special callback URL for testing purposes.

At the end of step 1, users will not be redirected to your app's callback URL and the authorization code will be displayed to you instead.

Refreshing access tokens

To enforce regular token rotation and reduce the impact of a compromised token, access tokens automatically expire after 8 hours. You can use refresh tokens to request new access token.

When you receive an access token, the response will also contain a refresh token, which can be exchanged for a new access token and refresh token.

To renew an expiring access token, you can exchange the refresh_token for a new access_token and refresh_token.

Tips: Use the refresh_token to get a new access_token when it has expired. refresh_token do not expire.

Exchange an OAuth code for a user's access token

POST https://app.textmaster.com/oauth/token

Query Parameters

Name	Type	Description
client_id*	String	The client ID you received from TextMaster when you registered your app.
client_secret*	String	The client secret you received from TextMaster when you registered your app.
grant_type*	String	Value must be refresh_token (required by the OAuth specification).
refresh_token*	String	The token received with the access_token.

200: OK

{
  "access_token":"1d9ac1a4eb8ebcdb90ceb0a681c83f12cc65",
  "token_type":"Bearer",
  "expires_in":28800,
  "refresh_token":"9081dbe2b7dfc3ffb4e0861e4f4c471d7",
  "scope":"public",
  "created_at":1605192507
}