Authentication & Authorization

Using Bot’s Typetalk Token

This is the simplist way to access Typetalk APIs. However, you can access APIs in “topic.read” or “topic.post” scope only. See also Typetalk Token Samples.

Get Typetalk Token

Create Bot in editing topic page and you can get Typetalk Token.

Access APIs using Typetalk Token

Access APIs with HTTP header, query parameter or form parameter including Typetalk Token.

Header

X-Typetalk-Token: YOUR_TYPETALK_TOKEN

Parameter

typetalkToken=YOUR_TYPETALK_TOKEN

Using OAuth 2.0

Access APIs using OAuth 2.0. Of course, you can use OAuth 2.0 client libraries.

Get access token using client credentials

Use client credentials if the application is only accessed by you. See also Client Credential Samples.

1. Register your application

Register your application on Developer Application page. Select “Client Credentials” as Grant Type.

2. Get an access token

Method

POST

URL

https://typetalk.com/oauth2/access_token

Form parameters

Name	Description
client_id	Getting from the Developer Application page
client_secret	Getting from the Developer Application page
grant_type	”client_credentials” (Fixed value)
scope	Refer to About scope.

Successful response (200)

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "YOUR_REFRESH_TOKEN"
}

Example of failed response (400 or 401)

{
    "error": "invalid_request",
    "error_description": "grant_type not found"
}

Get access token using authorization code

Use authorization code if the application is also accessed by others apart from yourself. See also Authorization Code Samples.

1. Register your application

Register your application on Developer Application page. Select “Authorization Code” as Grant Type.

2. Authorize the user

Make the user access the following url.

Method

GET

URL

https://typetalk.com/oauth2/authorize

Query parameters

Name	Description
client_id	Getting from the Developer Application page
redirect_uri	The same URI you set on the Developer Application page
scope	Refer to About scope.
response_type	”code” (Fixed value)
state (Optional)	A random string. It is used to protect against cross-site request forgery attacks.

3. Get authorization code

We call your redirect_uri with authorization code after the user authorized your application.

REDIRECT_URI?code=YOUR_CODE

4. Get an access token using authorization code

Method

POST

URL

https://typetalk.com/oauth2/access_token

Form parameters

Name	Description
client_id	Getting from the Developer Application page
client_secret	Getting from the Developer Application page
redirect_uri	The same URI you set on the Developer Application page
grant_type	”authorization_code” (Fixed value)
code	YOUR_CODE

Successful response (200)

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "YOUR_REFRESH_TOKEN"
}

Example of failed response (400 or 401)

{
    "error": "invalid_request",
    "error_description": "grant_type not found"
}

Access APIs using access token

Access APIs with HTTP header, query parameter or form parameter including access_token.

Header

Authorization: Bearer YOUR_ACCESS_TOKEN

Parameter

access_token=YOUR_ACCESS_TOKEN

* Encountering errors

Authentication failure may return status code 400 or 401. The error message can be found in the WWW-Authenticate header. The following are examples of error messages:

Access token is not specified

WWW-Authenticate: Bearer error="invalid_request", error_description="Access token is not found"

Access token is invalid

WWW-Authenticate: Bearer error="invalid_token", error_description="The access token is not found"

Access token is expired

WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"

Accessing API out of specified scope

WWW-Authenticate: Bearer error="invalid_scope"

Refresh access token

An access token expires in 3600 seconds (1 hour). You can get new access token by using your refresh token. A refresh token expires in 30 days.

Method

POST

URL

https://typetalk.com/oauth2/access_token

Form parameters

Name	Description
client_id	Getting from the Developer Application page
client_secret	Getting from the Developer Application page
grant_type	”refresh_token” (Fixed value)
refresh_token	YOUR_REFRESH_TOKEN

Successful response (200)

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "YOUR_REFRESH_TOKEN"
}

Example of failed response (400 or 401)

{
    "error": "invalid_request",
    "error_description": "grant_type not found"
}

About scope

Specify the scope of APIs you can use. Use spaces to separate scopes when using more than one scope.

Value	Description
topic.read	Get messages in topics
topic.post	Post messages to topics and like messages
topic.write	Create and update topics
topic.delete	Delete topics
my	Get topic list, profile, notifications and save bookmarks
organization.read	Get organization data