Contents

認証と認可

Typetalk トークンを使用

Typetalk API を使うもっとも簡単な方法です。“topic.read” または “topic.post” スコープの API だけアクセスできます。 Typetalk トークンのサンプルも参照してください.

Typetalk トークンを取得

トピックの編集ページから “ボット” を作成し、Typetalk トークンを取得します。

Typetalk トークンで API にアクセス

HTTPヘッダやクエリパラメータ、フォームパラメータのいずれかに Typetalk トークンを含めて、APIにアクセスしてください

ヘッダ

X-Typetalk-Token: YOUR_TYPETALK_TOKEN

パラメータ

typetalkToken=YOUR_TYPETALK_TOKEN

OAuth 2.0 を使用

OAuth 2.0 を使って API にアクセスします。もちろん、OAuth 2.0 のクライアントライブラリを使うこともできます。

Client Credential を使ってアクセストークンを取得

あなただけが使用するアプリケーションにはClient Credential を使います。 Client Credential のサンプルも参照してください。

1. アプリケーションの登録

開発アプリケーション ページからアプリケーションを登録してください。Grant Typeには”Client Credentials”を選択してください。

2. アクセストークンの取得

メソッド
POST
URL
https://typetalk.com/oauth2/access_token
フォームパラメーター
名前説明
client_id開発アプリケーション ページから取得
client_secret開発アプリケーション ページから取得
grant_type”client_credentials” (固定値)
scopeスコープについて 参照

成功レスポンス (200)

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

失敗レスポンスの例 (400 または 401)

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

Authorization Code を使ってアクセストークンを取得

誰かに利用してもらうアプリケーションでは、 Authorization Code を使います。Authorization Code のサンプルも参照してください。

1. アプリケーションの登録

開発アプリケーション ページからアプリケーションを登録してください。Grant Typeには”Authorization Code”を選択してください。

2. ユーザの認証

ユーザを以下のURLに遷移させてください。

メソッド
GET
URL
https://typetalk.com/oauth2/authorize
クエリパラメーター
名前説明
client_id開発アプリケーション ページから取得
redirect_uri開発アプリケーション ページで設定したものと同じUri
scopeスコープについて 参照
response_type”code” (固定値)
state (任意)ランダムな文字列.Cross-Site Request Forgery(CSRF)攻撃から保護するために使用されます.

3. 認証コードの取得

ユーザがあなたのアプリケーションを許可すると、 redirect_uri が認証コード付きで呼び出されます。

REDIRECT_URI?code=YOUR_CODE

4. 認証コードからアクセストークンを取得

メソッド
POST
URL
https://typetalk.com/oauth2/access_token
フォームパラメーター
名前説明
client_id開発アプリケーション ページから取得
client_secret開発アプリケーション ページから取得
redirect_uri開発アプリケーション ページで設定したものと同じUri
grant_type”authorization_code” (固定値)
codeYOUR_CODE

成功レスポンス (200)

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

失敗レスポンスの例 (400 または 401)

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

アクセストークンでAPIにアクセス

HTTPヘッダやクエリパラメータ、フォームパラメータのいずれかにアクセストークンを含めて、APIにアクセスしてください

ヘッダ

Authorization: Bearer YOUR_ACCESS_TOKEN

パラメータ

access_token=YOUR_ACCESS_TOKEN

* エラーについて

認証エラーの場合、ステータスコードが 400 または 401 となります。エラーメッセージは、 レスポンスヘッダを確認してください。主なエラーは以下の通りです。

アクセストークンが指定されていない

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

アクセストークンが間違っている

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

アクセストークンが有効期限切れ

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

スコープ権限のないAPIにアクセスした

WWW-Authenticate: Bearer error="invalid_scope"

アクセストークンを更新

アクセストークンは3600秒（1時間）で有効期限切れになります。リフレッシュトークンを使って新しいアクセストークンを取得することができます。リフレッシュトークンの有効期限は30日です。

メソッド

POST

URL

https://typetalk.com/oauth2/access_token

フォームパラメーター

名前説明
client_id開発アプリケーション ページから取得
client_secret開発アプリケーション ページから取得
grant_type”refresh_token” (固定値)
refresh_tokenYOUR_REFRESH_TOKEN

成功レスポンス (200)

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

失敗レスポンスの例 (400 または 401)

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

スコープについて

使用できるAPIの範囲を指定します。一つ以上指定したい場合はスペース区切りで指定してください。

値説明
topic.readトピック中のメッセージの取得
topic.postトピックにメッセージを投稿、メッセージにいいね！する
topic.writeトピックの作成や更新
topic.deleteトピックの削除
myトピック一覧、プロフィール、通知の取得、既読の更新
organization.read組織情報の取得