Botframework-sdk: DirectLine API - tokens

[hailiang-wang]

Description

After testing the DirectLine APIs, the tokens mechanism make me confused. There seems to be two kinds of tokens.

Token A

GET _directline.botframework.com/api/tokens/conversation_ with secret.

response like

"snoZV1.VwK70lrh0QE.XjC4myqA.jLNFfuUTwDSbg2PUmpmfdDNmADHZ9j"

Token B

POST _https://directline.botframework.com/api/conversations_ with scoped token

response

{
  "conversationId": "xCjEVbPx",
  "token": "snoZV1MiBEA.dAA.X6Z58Vrh0QE.B2j5V2cyxC0.DDEHtqi1WCsOyqUi6GKpwoE-b35eOYxVglGcY9kYsmg"
}

compare the functions

• Token A and Token B can be used with
  POST|GET https://directline.botframework.com/api/conversations/{{Conversation_ID}}/messages
• Only Token B can be used with
  GET https://directline.botframework.com/api//tokens/{{Conversation_ID}}/renew

if token A is used, get error message

{
  "message": "This method can only be used to renew an existing conversation token"
}

• Both Token A and Token B can not be used with
  POST https://directline.botframework.com/api/tokens/conversation

{
  "message": "Cannot use a scoped token to generate a different scoped token"
}

So, can you given a clear doc with these tokens?

[dandriscoll]

It may be clearer with different names.

A secret can be used in any conversation and never expires. (This is labeled "Token A" above)
A token can only be used in one conversation and expires. (This is labeled "Token B.")

You can use either a secret or a token to send/receive messages via the POST/GET /api/conversations/id/messages endpoint. Service-to-service applications typically use secrets. Thin client applications (like JavaScript in webpages) usually exchange a secret for a token so the secret is not exposed to clients. The client only receives a token that's good for one conversation and for a limited amount of time.

POST /api/tokens/conversation is used to convert a secret into a token. Thus, you can only use a secret.
GET /api/tokens/id/renew is used to renew a token. Thus, you can only use a token.

Does that clarify sufficiently?

[hailiang-wang]

yes, thanks, it is much more clear now. 👍

[ambrishverma]

I am trying to initiate a new conversation while passing secret. I am calling as:
curl -X POST --header 'Accept: application/json' 'https://directline.botframework.com/api/conversations?secret=XXXX'

but I keep getting error:
{
"message": "Missing token or secret"
}

Could you please suggest what is the correct way to pass secret.