Authentication in Direct Line API 1.1
Important
This article describes authentication in Direct Line API 1.1. If you're creating a new connection between your client application and bot, use Direct Line API 3.0 instead.
A client can authenticate requests to Direct Line API 1.1 either by using a secret that you obtain from the Direct Line channel configuration page in the Bot Framework Portal or by using a token that you obtain at runtime.
The secret or token should be specified in the Authorization header of each request, using either the "Bearer" scheme or the "BotConnector" scheme.
Bearer scheme:
Authorization: Bearer SECRET_OR_TOKEN
BotConnector scheme:
Authorization: BotConnector SECRET_OR_TOKEN
Secrets and tokens
A Direct Line secret is a master key that can be used to access any conversation that belongs to the associated bot. A secret can also be used to obtain a token. Secrets don't expire.
A Direct Line token is a key that can be used to access a single conversation. A token expires but can be refreshed.
If you're creating a service-to-service application, specifying the secret in the Authorization header of Direct Line API requests may be simplest approach. If you're writing an application where the client runs in a web browser or mobile app, you may want to exchange your secret for a token (which only works for a single conversation and will expire unless refreshed) and specify the token in the Authorization header of Direct Line API requests. Choose the security model that works best for you.
Note
Your Direct Line client credentials are different from your bot's credentials. This enables you to revise your keys independently and lets you share client tokens without disclosing your bot's password.
Get a Direct Line secret
You can obtain a Direct Line secret via the Direct Line channel configuration page for your bot in the Azure portal:
Generate a Direct Line token
To generate a Direct Line token that can be used to access a single conversation, first obtain the Direct Line secret from the Direct Line channel configuration page in the Azure portal. Then issue this request to exchange your Direct Line secret for a Direct Line token:
POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer SECRET
In the Authorization header of this request, replace SECRET with the value of your Direct Line secret.
The following snippets provide an example of the Generate Token request and response.
Request
POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Response
If the request is successful, the response contains a token that is valid for one conversation. The token will expire in 30 minutes. For the token to remain useful, you must refresh the token before it expires.
HTTP/1.1 200 OK
[other headers]
"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn"
Generate Token versus Start Conversation
The Generate Token operation (POST /api/tokens/conversation) is similar to the Start Conversation operation (POST /api/conversations) in that both operations return a token that can be used to access a single conversation. However, unlike the Start Conversation operation, the Generate Token operation doesn't start the conversation or contact the bot.
If you plan to distribute the token to clients and want them to initiate the conversation, use the Generate Token operation. If you intend to start the conversation immediately, use the Start Conversation operation instead.
Refresh a Direct Line token
A Direct Line token is valid for 30 minutes from the time it's generated and can be refreshed an unlimited number of times, as long as it hasn't expired. An expired token can't be refreshed. To refresh a Direct Line token, issue this request:
POST https://directline.botframework.com/api/tokens/{conversationId}/renew
Authorization: Bearer TOKEN_TO_BE_REFRESHED
In the URI of this request, replace {conversationId} with the ID of the conversation for which the token is valid and in the Authorization header of this request, replace TOKEN_TO_BE_REFRESHED with the Direct Line token that you want to refresh.
The following snippets provide an example of the Refresh Token request and response.
Request
POST https://directline.botframework.com/api/tokens/abc123/renew
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn
Response
If the request is successful, the response contains a new token that is valid for the same conversation as the previous token. The new token will expire in 30 minutes. For the new token to remain useful, you must refresh the token before it expires.
HTTP/1.1 200 OK
[other headers]
"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0"
Additional resources
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for