Authentication

A client can authenticate requests to Direct Line API 3.0 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 this format:

Authorization: Bearer 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 do not 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 Bot Framework Portal:

Direct Line configuration

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 Bot Framework Portal. Then issue this request to exchange your Direct Line secret for a Direct Line token:

POST https://directline.botframework.com/v3/directline/tokens/generate
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/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

Response

If the request is successful, the response contains a token that is valid for one conversation and an expires_in value that indicates the number of seconds until the token expires. For the token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800
}

Generate Token versus Start Conversation

The Generate Token operation (POST /v3/directline/tokens/generate) is similar to the Start Conversation operation (POST /v3/directline/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 does not start the conversation, does not contact the bot, and does not create a streaming WebSocket URL.

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 can be refreshed an unlimited amount of times, as long as it has not expired. An expired token cannot be refreshed. To refresh a Direct Line token, issue this request:

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer TOKEN_TO_BE_REFRESHED

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/v3/directline/tokens/refresh
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 and an expires_in value that indicates the number of seconds until the new token expires. For the new token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Additional resources