# Authorizing OAuth Apps

TextMaster's OAuth implementation supports the standard [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1).

See the [skip authorization](#skip-authorization-for-testing-purposes) 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](https://tools.ietf.org/html/rfc6749#section-4.2) 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

<mark style="color:blue;">`GET`</mark> `https://app.textmaster.com/oauth/authorize`

#### Query Parameters

| Name                                             | Type   | Description                                                              |
| ------------------------------------------------ | ------ | ------------------------------------------------------------------------ |
| client\_id<mark style="color:red;">\*</mark>     | String | The client ID you received from TextMaster when you registered your app. |
| redirect\_uri<mark style="color:red;">\*</mark>  | String | The callback URL that is configured in your registered app.              |
| scope<mark style="color:red;">\*</mark>          | String | A space-delimited list of scopes.                                        |
| response\_type<mark style="color:red;">\*</mark> | String | Value must be `code` (required by the OAuth specification).              |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

```shell
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'
```

![](https://2001322700-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiLJk7NFk70NqFY1GU7Oi%2Fuploads%2FPOQ7OziK6fD6Od7Wh4Zx%2Fauthorizing-oauth-app.png?alt=media\&token=7680419d-4344-41eb-9ca5-12e269dfbb74)

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

<mark style="color:green;">`POST`</mark> `https://app.textmaster.com/oauth/token`

#### Query Parameters

| Name                                             | Type   | Description                                                                  |
| ------------------------------------------------ | ------ | ---------------------------------------------------------------------------- |
| client\_id<mark style="color:red;">\*</mark>     | String | The client ID you received from TextMaster when you registered your app.     |
| client\_secret<mark style="color:red;">\*</mark> | String | The client secret you received from TextMaster when you registered your app. |
| grant\_type<mark style="color:red;">\*</mark>    | String | Value must be `authorization_code` (required by the OAuth specification).    |
| redirect\_uri                                    | String | The same callback URL as sent in step 1.                                     |
| code<mark style="color:red;">\*</mark>           | String | The `code` you received as a response to step 1.                             |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}
{% endtabs %}

```shell
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

{% hint style="info" %}
**Tips:** Access token expires after 8 hours. For more information about refresh tokens, see [Refreshing access tokens](#undefined).
{% endhint %}

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

<mark style="color:blue;">`GET`</mark> `https://api.textmaster.com/v1/clients/users/me`

#### Headers

| Name                                     | Type   | Description         |
| ---------------------------------------- | ------ | ------------------- |
| Accept<mark style="color:red;">\*</mark> | 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`.

{% hint style="info" %}
**Tips:** Use `urn:ietf:wg:oauth:2.0:oob` special callback URL for testing purposes.
{% endhint %}

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`.

{% hint style="info" %}
**Tips:** Use the `refresh_token` to get a new `access_token` when it has expired. `refresh_token` do not expire.
{% endhint %}

## Exchange an OAuth code for a user's access token

<mark style="color:green;">`POST`</mark> `https://app.textmaster.com/oauth/token`

#### Query Parameters

| Name                                             | Type   | Description                                                                  |
| ------------------------------------------------ | ------ | ---------------------------------------------------------------------------- |
| client\_id<mark style="color:red;">\*</mark>     | String | The client ID you received from TextMaster when you registered your app.     |
| client\_secret<mark style="color:red;">\*</mark> | String | The client secret you received from TextMaster when you registered your app. |
| grant\_type<mark style="color:red;">\*</mark>    | String | Value must be `refresh_token` (required by the OAuth specification).         |
| refresh\_token<mark style="color:red;">\*</mark> | String | The token received with the `access_token`.                                  |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}
{% endtabs %}