認証と認可

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” (固定値)

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” (固定値)
code YOUR_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_token YOUR_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 トピック一覧、プロフィール、通知の取得、既読の更新