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.

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