The TEXTKING API is using oAuth 2.0 with the Authorization Code Grant Workflow to authorize access to the API. In order for your application to access the API, you have to follow a simple 4-steps process:

1. Register your application and obtain an app ID.
2. Let the user authorize the API access through your application.
3. Using the authorization obtain an access token and store it in your application.
4. Use the access token to perform API requests.

Go to www.textking.com and log into your user account. If you have no account yet, you can create a new one. When logged in you can access the API Configuration under “My Data”.

Click on “Register new application” and add a name for your new application. The newly registered application will show up in the list together with a new App ID and App Secret. You will need the ID and the Secret in the following steps. You should keep both the App ID and App Secret confidential, since they can be used to perform API requests under your name.

Inside your application if the user wants to access the API for the first time, you have to let him authorize the access to his TEXTKING account. To do so, the application should redirect the user to the URL https://www.textking.com/oauth/authorize with the following query string parameters:

Parameter	Description
response_type	Always code
client_id	The App ID (see step 1)
redirect_uri	The user will be redirected to this callback URL after he authorized your app.
state	OPTIONAL An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery

Example authorize URL:

https://www.textking.com/oauth/authorize?response_type=code&client_id=afcf6642-019b-45f8-b6c6-d00c1f73931b&redirect_uri=https://example.com/myapp/authorize_response&state=anyrandomstring

After successful authorization the user will be redirected to the callback URL specified by you with the redirect_uri parameter. TEXTKING will pass two parameters to this URL, code and state. code will include the authorization code you need in the next step to get access to the API. state will be exactly the string you passed in your original request. This can be used to verify that the call to your callback URL really belongs to your original request.

Example callback:

https://example.com/myapp/authorize_response?code=CC0M%21IAAAAMrtH3Mow...E91o0Q_I1aHlF&state=anyrandomstring

The authorization code you got in the last step should now be used to obtain an access token. To do this, you have to send a POST request to https://www.textking.com/oauth/token, whith the following parameters encoded in the request body as “application/x-www-form-urlencoded”:

Parameter	Description
grant_type	Always authorization_code
client_id	The App ID (see step 1)
client_secret	The App Secret (see step 1)
code	The authorization code you got in step 2
redirect_uri	Exactly the same redirect URI you specified in step 2
offline_access	OPTIONAL If set to 1, the access token will be valid indefinitely. If you don’t set this parameter the access token will expire after 30 days, but it can be renewed using the refresh token (see below.)

Note: Make sure you properly urlencode all the parameter values. The client ID and client secret can contain special characters, e.g. a ‘+’ sign, and the server will not accept the parameter if not encoded properly.

Example request:

POST /oauth/token HTTP/1.1
Host: www.textking.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=afcf6642-019b-45f8-b6c6-d00c1f73931b&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw&redirect_uri=https://example.com/myapp/authorize_response&code=CC0M%21IAAAAMrtH3Mow...E91o0Q_I1aHlF

The response to this request will contain the access token and refresh token in a JSON structure.

Example response:

{
    "access_token": "gAAAAMmcvm7glkOV4YJCJZZgcP...peHW7lDbtJCtCQcNE7ui40D7gfe3ybaU",
    "token_type": "bearer",
    "expires_in": "2592000",
    "refresh_token": "W1fl!IAAAAJBy7kE3DsBljtNo...sGq-pbLIsqLGfshaLISQnT8vcWwqL8Wg"
}

The token_type is always bearer. Both expires_in and refresh_token will not be present if you used the offline_access=1 parameter. Otherwise expires_in specifies the lifetime of you access token in seconds.

You should store both the access token and the refresh token securely inside your application.

If your access token has expired, you can use the refresh token to obtain a new access token. For this send a POST request to https://www.textking.com/oauth/token, with the following parameters encoded in the request body as “application/x-www-form-urlencoded”:

Parameter	Description
grant_type	Always refresh_token
client_id	The App ID (see step 1)
client_secret	The App Secret (see step 1)
refresh_token	The refresh token

Example request:

POST /oauth/token HTTP/1.1
Host: www.textking.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=W1fl!IAAAAJBy7kE3DsBljtNo...sGq-pbLIsqLGfshaLISQnT8vcWwqL8Wg

The response to this request is similar to the response in step 3.

You can now use the the access token to perform API requests. To authenticate against the server, you have to add an Authorization HTTP header containing the access token to every API request as shown below:

GET /v1/projects HTTP/1.1
Host: api.textking.com
Accept: application/json
Authorization: Bearer gAAAAMmcvm7glkOV4YJCJZZgcP...peHW7lDbtJCtCQcNE7ui40D7gfe3ybaU

If the Authorization header is missing or invalid the service will respond with a status code 403 Forbidden. See Using the service for more details on using the service itself.