> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtain the access credential of a signed-in user

> Obtain the access credential for an app to call DingTalk OpenAPI on behalf of a signed-in user through four steps: app creation, OAuth authorization, credential retrieval, and API call.

When an app needs to call DingTalk OpenAPI on behalf of a signed-in user to operate on resources, follow the procedure in this topic to obtain the access credential for calling APIs.

<Note>
  The process for internal apps and third-party enterprise apps is similar. This topic uses an internal app as an example.
</Note>

## Step 1: Create an app

1. Sign in to the [DingTalk Developer Platform](https://open-dev.dingtalk.io/#/loginMan).

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

To use DingTalk OpenAPI to read and write resources on behalf of a user, complete authorization through the OAuth 2.0 authorization flow. The OAuth 2.0 authorization flow is illustrated below.

### Use the sign-in authorization page provided by DingTalk

Construct the sign-in authorization page. The page parameters are as follows:

### 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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```

| Name            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| redirect\_uri   | Yes      | The callback URL after authorization is granted or declined.  **Important**  Must match the domain registered for the app.                                                                                                                                                                                                                                                                                                                       |
| response\_type  | Yes      | A fixed value of code.  Returns authCode after authorization is granted.                                                                                                                                                                                                                                                                                                                                                                         |
| client\_id      | Yes      | Obtained from the app details created in Step 1.   - Internal app: client\_id is the App Key of the app. - Third-party enterprise app: client\_id is the SuiteKey of the app.                                                                                                                                                                                                                                                                    |
| scope           | Yes      | The authorization scope. The authorization information displayed on the authorization page is based on the configuration at app registration.  Currently, only two values are supported:   - **openid**: After authorization, the user ID is obtained. - **openid** corpid: After authorization, the user ID and the organization ID selected by the user during sign-in are obtained, separated by a space. Note that URL encoding is required. |
| prompt          | Yes      | When set to consent, the authorization confirmation page is displayed.                                                                                                                                                                                                                                                                                                                                                                           |
| state           | No       | Returned as-is along with the authCode.                                                                                                                                                                                                                                                                                                                                                                                                          |
| org\_type       | No       | Controls the output of a specific type of organization list. org\_type=management indicates that only organizations with administrative permissions are returned.  **Important**  This parameter is meaningful only when scope contains corpid.                                                                                                                                                                                                  |
| corpId          | No       | Specifies the organization that the user must select.  **Important**   - This parameter is meaningful only when scope contains corpid. - The corpId passed in must be an organization the current user belongs to.                                                                                                                                                                                                                               |
| exclusiveLogin  | No       | When set to true, indicates exclusive account sign-in and displays the Organization Code input page.                                                                                                                                                                                                                                                                                                                                             |
| exclusiveCorpId | No       | The corpId of an organization with the exclusive account feature enabled.  **Important**  This parameter is meaningful only when exclusiveLogin is true,  and it redirects directly to the sign-in page of that organization.                                                                                                                                                                                                                    |

On success, redirects to: [https://www.aaaaa.com/a/b?authCode=xxxx\&state=dddd](https://www.aaaaa.com/a/b?authCode=xxxx\&state=dddd)

On failure, redirects to: [https://www.aaaaa.com/a/b?error=yyyyyy\&state=dddd](https://www.aaaaa.com/a/b?error=yyyyyy\&state=dddd)

### Embedded QR Code sign-in authorization

<Warning>
  The page that embeds the QR Code must be "same-origin" with the page specified by the redirect\_uri parameter. Otherwise, scanning the QR Code will have no effect. "Same-origin" means the same protocol, same second-level or third-level domain, same port number, and so on. For details, see [Same-origin policy](https://developer.mozilla.org/zh-CN/docs/Web/Security/Same-origin_policy).
</Warning>

1. Include the DingTalk Scan QR Code sign-in JSSDK in the page.

   ```xml theme={"theme":{"light":"github-light","dark":"github-dark"}}
   <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.

   ```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
   <!-- 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):

   ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
   // ********************************************************************************
   // 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

Use the returned auth\_code and the app information to call the [Get user token](/open/development/obtain-user-token) API to obtain the access\_token.

Sample code:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

After obtaining the access\_token, you can use this credential to call the [Get user contact profile](/open/development/dingtalk-retrieve-user-information) API.