Obtain the access credential of a signed-in user

​

Step 1: Create an app

1. Sign in to the DingTalk Developer Platform.
2. Open the details page of the app you have created. On the Basic Information page, view the app’s SuiteKey/SuiteSecret (Third-party enterprise app) or AppKey/AppSecret (Internal app).
3. On the app details page, click Development Configuration > Security Settings, and enter the redirect URI (callback domain).

   The redirect URI is the address you expect to be redirected to after sign-in authorization.

​

Step 2: OAuth sign-in authorization

​

Use the sign-in authorization page provided by DingTalk

​

Important

• For readability, line breaks are added to the following parameter example. Line breaks are not required in actual use.
• Parameter values must be URL-encoded. The following example has already been URL-encoded.

https://login.dingtalk.io/oauth2/auth?
redirect_uri=https%3A%2F%2Fwww.aaaaa.com%2Fa%2Fb
&response_type=code
&client_id=dingbbbbbbb
&scope=openid corpid
&state=dddd
&prompt=consent

​

Embedded QR Code sign-in authorization

1. Include the DingTalk Scan QR Code sign-in JSSDK in the page.
   <script src="https://g.alicdn.com/dingding/h5-dingtalk-login/0.21.0/ddlogin.js"></script>
   
2. Call the following method where the Scan QR Code sign-in is required.
   <!-- STEP1: Add the wrapper container element in HTML -->
   <div id="self_defined_element" class="self-defined-classname"></div>
   <style>
       /* STEP2: Specify the CSS style for this wrapper container element. Pay special attention to width and height. */
       .self-defined-classname {
           width: 300px;
           height: 300px;
       }
   </style>
   <script>
       // STEP3: When needed, call the window.DTFrameLogin method to construct the sign-in QR Code and handle the success or failure callbacks.
       window.DTFrameLogin(
           {
               id: 'self_defined_element',
               width: 300,
               height: 300,
           },
           {
               redirect_uri: encodeURIComponent('http://www.aaaaa.com/a/b/'),
               client_id: 'dingxxxxxxxxxxxx',
               scope: 'openid',
               response_type: 'code',
               state: 'xxxxxxxxx',
               prompt: 'consent',
           },
           (loginResult) => {
               const {redirectUrl, authCode, state} = loginResult;
               // You can redirect directly here
               window.location.href = redirectUrl;
               // Or use the code for authorization without redirecting the page
               console.log(authCode);
           },
           (errorMsg) => {
               // Typically, display the specific reason for the sign-in failure here
               alert(`Login Error: ${errorMsg}`);
           },
       );
   </script>
   
   Parameter description (in TypeScript):
   // ********************************************************************************
   // Definition of the window.DTFrameLogin method
   // ********************************************************************************
   window.DTFrameLogin: (
     frameParams: IDTLoginFrameParams, // Parameters related to the DOM wrapper container
     loginParams: IDTLoginLoginParams, // Unified sign-in parameters
     successCbk: (result: IDTLoginSuccess) => void, // Callback function on successful sign-in
     errorCbk?: (errorMsg: string) => void,         // Callback function on failed sign-in
   ) => void;
   
   // ********************************************************************************
   // Parameters related to the DOM wrapper container
   // ********************************************************************************
   // Note! The width and height parameters only set the size of the QR Code iframe element and do not affect the size of the wrapper container.
   // The size and style of the wrapper container must be set by the integrator using CSS.
   interface IDTLoginFrameParams {
     id: string;      // Required. The ID of the wrapper container element, without '#'.
     width?: number;  // Optional. The width of the QR Code iframe element. Minimum 280. Default 300.
     height?: number; // Optional. The height of the QR Code iframe element. Minimum 280. Default 300.
   }
   
   // ********************************************************************************
   // Unified sign-in parameters
   // ********************************************************************************
   // The parameter meanings are identical to those in the "Construct a link to initiate sign-in authorization" integration method (with some parameters omitted).
   // The isPre parameter is added to set the runtime environment.
   interface IDTLoginLoginParams {
     redirect_uri: string;     // Required. Note that the URL must be encoded.
     response_type: string;    // Required. A fixed value of code.
     client_id: string;        // Required.
     scope: string;            // Required. If the value is openid+corpid, the org_type and corpId parameters below are required. Otherwise, sign-in will fail.
     prompt: string;           // Required. The value is consent.
     state?: string;           // Optional.
     org_type?: string;        // Optional. Required when scope is openid+corpid.
     corpId?: string;          // Optional. Required when scope is openid+corpid.
     exclusiveLogin?: string;  // Optional. To generate a QR Code dedicated to an exclusive organization, set this to true to restrict sign-in to organization accounts only.
     exclusiveCorpId?: string; // Optional. Required when exclusiveLogin is true. Specifies the corpId of the exclusive organization.
   }
   
   // ********************************************************************************
   // Sign-in result returned on successful sign-in
   // ********************************************************************************
   interface IDTLoginSuccess {
     redirectUrl: string;   // The redirect URL after successful sign-in. The integrator can use this URL directly for redirection.
     authCode: string;      // The authCode obtained after successful sign-in. The integrator can authenticate directly without redirecting the page.
     state?: string;        // The state obtained after successful sign-in.
   }
   

​

Step 3: Obtain the access credential

POST /v1.0/oauth2/userAccessToken HTTP/1.1
Host:api.dingtalk.io
x-acs-dingtalk-access-token:BE3xxxx
Content-Type:application/json

{
  "clientId" : "dingxxx",
  "clientSecret" : "1234",
  "code" : "abcd",
  "refreshToken" : "abcd",
  "grantType" : "authorization_code"
}

​

Step 4: Call APIs with the access credential