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

通过 Java SDK 方式调用扣子编程 OpenAPI 时，需要在 SDK 请求中配置访问密钥，用于身份信息认证和权限校验。扣子编程 OpenAPI 提供个人访问密钥和 OAuth 两种鉴权方式，你可以选择当前业务场景适合的鉴权方式，并获取对应的访问密钥。
对于 OAuth 授权码等授权方式，Coze Java SDK 已经封装了这部分代码，并处理了不同的返回错误代码，简化你的操作。
## 配置方式 {#73e164bf}
扣子编程 OpenAPI 目前支持的鉴权方式如下。
<!-- @cols-width: 169,173,335,279 -->
| | | | | \
|**访问密钥类型** |**鉴权方式** |**说明** |**示例文件** |
|---|---|---|---|
| | | | | \
|个人访问密钥（PAT） |个人访问密钥（PAT） |Personal Access Token，简称 PAT。扣子编程中生成的个人访问令牌。PAT 生成与使用便捷，适用于测试环境调试等场景。每个令牌可以关联多个空间，并开通指定的接口权限。生成方式可参考[添加个人访问令牌](https://www.coze.cn/docs/developer_guides/pat)。 |[TokenAuthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/TokenAuthExample.java) |
| | | |^^| \
|服务访问令牌（SAT） |服务访问令牌（SAT） |Service Access Token（简称 SAT）是以服务身份创建的访问凭证，可**长期有效**访问扣子编程资源，通常用于服务/应用程序的身份验证和授权。SAT 与 OAuth JWT 鉴权方式相比，具有更长的有效期（可设置为永久有效），操作简单，能够有效简化授权流程。生成方式可参考[添加服务访问令牌](/developer_guides/service_token)。 |\
| | |SAT 的示例代码与 PAT 通用，可直接参考 PAT 的示例文件。 | |
| | | | | \
|OAuth 认证 |\
| |授权码授权  |\
| |（Authorization Code Flow）  |适用于有显著前后端之分的应用程序授权场景。其中前端模块负责与用户交互，后端服务处理前端请求，与扣子授权服务器和 OpenAPI 交互。 实现流程可参考[OAuth 授权码授权](/developer_guides/oauth_code)。 |[WebOAuthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/WebOAuthExample.java) |
|^^| | | | \
| |PKCE 授权  |\
| |（Authorization Code Flow with PKCE）  |应用程序无后端服务，所有操作都发生在应用程序的前端。 实现流程可参考[OAuth PKCE](/developer_guides/oauth_pkce)。 |[PKCEOauthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/PKCEOAuthExample.java) |
|^^| | | | \
| |设备码授权  |\
| |（Device Code Flow）  |应用程序无后端服务，所有操作都发生在应用程序的 Command Line，且 Command Line 无法提供“同意授权”的操作。 实现流程可参考[OAuth 设备授权](/developer_guides/oauth_device_code)。 |[DevicesOAuthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/DevicesOAuthExample.java) |
|^^| | | | \
| |JWT 授权  |\
| |（JWT Flow）  |应用程序服务端直接调用扣子编程 OpenAPI。  |\
| | |应用程序后端服务代理应用程序自己的用户获取身份凭据，应用程序用户基于凭据直接访问 OpenAPI。 实现流程可参考[OAuth JWT 授权（开发者）](/developer_guides/oauth_jwt)。 |[JWTsOauthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/JWTOAuthExample.java) |

## 配置个人访问密钥（PAT） {#364507dd}
如果选择使用个人访问密钥鉴权，你需要先申请一个个人访问密钥，并添加指定空间和权限。操作步骤可参考[添加个人访问令牌](https://www.coze.cn/docs/developer_guides/pat)。完整的示例代码请参见 [TokenAuthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/TokenAuthExample.java)。
扣子编程建议你通过环境变量的方式管理访问密钥，避免在代码中通过硬编码方式进行编程，以免密钥泄露、引发安全风险。配置环境变量之后，您可以在不修改代码的情况下，将动态的鉴权参数传递到对应的函数，实现便捷安全的身份认证。

1. 设置环境变量。
   其中 COZE_API_TOKEN 是扣子编程中申请的个人访问密钥。
   ```Shell
   export COZE_API_TOKEN=pat_****
   ```

2. 初始化客户端。
   示例代码如下：
   ```Java
   import com.coze.openapi.service.auth.TokenAuth;
   import com.coze.openapi.service.config.Consts;
   import com.coze.openapi.service.service.CozeAPI;
   import okhttp3.OkHttpClient;
   
   public class InitClientExample {
       public static void main(String[] args) {
           // 从环境变量中获取个人访问密钥（PAT）
           // 推荐使用环境变量管理密钥，避免硬编码导致泄露
           String token = System.getenv("COZE_API_TOKEN");
           
           // 创建TokenAuth对象，传入PAT作为身份认证凭据
           TokenAuth authCli = new TokenAuth(token);
   
           // 构建CozeAPI客户端实例，配置连接参数
           CozeAPI coze =
               new CozeAPI.Builder()
                   .baseURL(Consts.COZE_CN_BASE_URLCOZE_COM_BASE_URL)  // 设置扣子编程OpenAPI的 Endpoint
                   .auth(authCli)  // 绑定鉴权对象，用于请求时的身份验证
                   .client(new OkHttpClient.Builder().build())  // 配置HTTP客户端（使用默认OkHttpClient）
                   .build();  // 完成客户端初始化
       }
   }
   ```


## 配置 OAuth 授权码流程 {#b1e6ad12}
如果选择使用 OAuth 授权码方式完成授权，可参考以下流程及示例代码。完整的示例代码请参见 [WebOAuthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/WebOAuthExample.java)。

1. 创建 OAuth 应用。
   具体操作步骤可参考[OAuth 授权码授权](/developer_guides/oauth_code)。成功创建 OAuth 应用后，你将获得客户端 ID、客户端密钥和重定向地址。你需要妥善保管客户端密钥，以免数据泄露引发安全风险。
2. 在代码中通过环境变量方式设置客户端 ID、客户端密钥和重定向地址。
   ```Java
   public class PKCEOauthExample {
       public static void main(String[] args) {
           // 从环境变量中获取PKCE OAuth应用的重定向地址，创建PKCE类型OAuth应用时配置的前端回调地址
           String redirectURI = System.getenv("COZE_PKCE_OAUTH_REDIRECT_URI");
           
           // 从环境变量中获取PKCE OAuth应用的客户端ID，创建PKCE类型OAuth应用时平台生成的唯一标识符
           String clientID = System.getenv("COZE_PKCE_OAUTH_CLIENT_ID");
   
           // 创建PKCEOAuthClient实例，配置应用信息
           PKCEOAuthClient oauth =
               new PKCEOAuthClient.PKCEOAuthBuilder()
                   .clientID(clientID)  // 传入客户端ID，即从环境变量获取的PKCE应用客户端ID
                   // 设置扣子授权服务器端点，由扣子编程固定提供的授权服务地址
                   .baseURL(Consts.COZE_CN_BASE_URLCOZE_COM_BASE_URL)
                   .build();
   
   
           /*
            * 生成PKCE授权链接
            * 1. SDK自动生成code_verifier和code_challenge
            * 2. 授权链接包含code_challenge和回调地址，用于引导用户授权
            */
           // 生成授权链接及code_verifier，返回包含授权URL和code_verifier的响应对象
           GetPKCEAuthURLResp oauthURL =
               oauth.genOAuthURL(
                   redirectURI,  // 重定向地址，即从环境变量获取的PKCE应用回调地址
                   "state",  // 状态参数，用于防CSRF攻击，自定义字符串
                   // 指定code_challenge的生成算法，固定使用SHA-256算法（S256）
                   PKCEOAuthClient.CodeChallengeMethod.S256
               );
           System.out.println(oauthURL);
           
           // 打印SDK生成的code_verifier，SDK自动生成的随机字符串，用于后续换取令牌时验证
           System.out.println(oauthURL.getCodeVerifier());
           
           // 打印用户需要访问的授权链接，用户授权页面的URL，从GetPKCEAuthURLResp对象获取
           System.out.println(oauthURL.getAuthorizationURL());
   
   
           /*
            * 用户授权后，扣子会重定向到redirectURI，并在Query中携带code（授权码）
            */
           // 模拟从重定向地址Query中获取的授权码，用户授权后从redirectURI的Query参数（code）中提取
           String code = "mock code";
   
           /*
            * 用授权码和code_verifier换取访问令牌
            * 必须传入genOAuthURL返回的code_verifier，否则验证失败
            */
           OAuthToken resp = oauth.getAccessToken(code, redirectURI, oauthURL.getCodeVerifier());
           System.out.println(resp);  // 打印令牌信息
   
           // 使用access_token初始化Coze客户端
           CozeAPI coze =
               new CozeAPI.Builder()
                   // 用access_token创建鉴权对象，access_token从OAuthToken对象获取
                   .auth(new TokenAuth(resp.getAccessToken()))
                   .baseURL(cozeAPIBase)  // 设置OpenAPI服务端点
                   .build();
   
           // 令牌过期时，使用refresh_token刷新，refresh_token从OAuthToken对象获取
           resp = oauth.refreshToken(resp.getRefreshToken());
       }
   }
   ```

3. 授权码流程中，会自动生成一个扣子编程授权页面，然后将其发送给需要授权的用户。扣子用户可访问此链接，并根据页面提示完成授权流程。
   ```Java
    String oauthURL = oauth.getOAuthURL(redirectURI, null);
    System.out.println(oauthURL);
   
       /*
        * To restrict access to a specific WorkSpace, you can specify the WorkSpaceID when obtaining the URL.
         oauthURL = oauth.getOAuthURL(redirectURI, null, "workspaceID");
       System.out.println(oauthURL);
        * */
   ```

4. 用户点击同意授权按钮后，扣子编程网页会将请求重定向到授权链接中配置的重定向地址，并通过 Query 在地址中携带授权码和状态参数。
   通过授权码（OAuth code）调用 OpenAPI 接口即可获取 OAuth Access Token。示例代码如下：
   ```Java
    /*
            * 授权流程说明：
            * 1. 前端引导用户访问扣子授权页面，用户完成授权后，扣子会重定向到redirectURI
            * 2. 重定向地址的Query参数中会携带code（授权码）和state（状态参数，用于防CSRF）
            * 3. 后端从Query中提取code，用于换取访问令牌
            */
           // 模拟从重定向地址的Query中获取到的授权码，用户授权后从redirectURI的Query参数（code）中提取
           String code = "mock code";
   
           /*
            * 用授权码换取访问令牌（access_token）
            * 调用getAccessToken方法，传入code和redirectURI（需与授权时使用的地址一致）
            */
           OAuthToken resp = oauth.getAccessToken(code, redirectURI);
           System.out.println(resp);  // 打印令牌信息，包含访问令牌、过期时间等
   
           /*
            * 获取请求日志ID，用于问题排查，从令牌响应对象中通过getLogID()方法获取
            */
           System.out.println(resp.getLogID());
   
           // 使用获取到的access_token初始化Coze客户端
           CozeAPI coze =
               new CozeAPI.Builder()
                   // 用access_token创建鉴权对象，access_token从OAuthToken对象的getAccessToken()方法获取
                   .auth(new TokenAuth(resp.getAccessToken()))
                   // 设置OpenAPI服务端点，由扣子编程固定提供的OpenAPI访问地址
                   .baseURL(cozeAPIBase)
                   .build();
   
           /*
            * 令牌过期时，使用refresh_token刷新令牌，refresh_token从OAuthToken对象的getRefreshToken()方法获取
            */
           resp = oauth.refreshToken(resp.getRefreshToken());
   ```


## 配置 OAuth PKCE 授权流程 {#49962f9d}
如果选择使用 OAuth PKCE 方式完成授权，可参考以下流程及示例代码。完整的示例代码请参见 [PKCEOauthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/PKCEOAuthExample.java)。

1. 创建 OAuth 应用。
   具体操作步骤可参考[OAuth PKCE](/developer_guides/oauth_pkce)。成功创建 OAuth 应用后，你将获得客户端 ID 和重定向地址。
2. 在代码中通过环境变量方式设置客户端 ID 和重定向地址。
   ```Java
       public static void main(String[] args) {
           // 从环境变量中获取PKCE OAuth应用的重定向地址，创建PKCE类型OAuth应用时配置的前端回调地址
           String redirectURI = System.getenv("COZE_PKCE_OAUTH_REDIRECT_URI");
           
           // 从环境变量中获取PKCE OAuth应用的客户端ID，创建PKCE类型OAuth应用时平台生成的唯一标识符
           String clientID = System.getenv("COZE_PKCE_OAUTH_CLIENT_ID");
   
           // 创建PKCEOAuthClient实例，配置应用信息
           PKCEOAuthClient oauth =
               new PKCEOAuthClient.PKCEOAuthBuilder()
                   .clientID(clientID)  // 传入客户端ID，即从环境变量获取的PKCE应用客户端ID
                   // 设置扣子授权服务器端点，由扣子编程固定提供的授权服务地址
                   .baseURL(Consts.COZE_CN_BASE_URLCOZE_COM_BASE_URL)
                   .build();
   ```

3. 在代码中实现 OAuth PKCE 授权流程。
   客户端生成一个随机值 code_verifier，并根据指定算法将其转换为 code_challenge，算法通常使用 SHA-256 算法。然后基于回调地址、code_challenge 和 code_challenge_method，生成一个授权链接。
     其中 code_verifier 会由 SDK 生成，并与 URL 一起返回给调用方。
   ```Java
   GetPKCEAuthURLResp oauthURL =
       oauth.genOAuthURL(redirectURI, "state", PKCEOAuthClient.CodeChallengeMethod.S256);
   System.out.println(oauthURL);
   // The code verifier generated by the SDK
   System.out.println(oauthURL.getCodeVerifier());
   // URL that users need to click.
   System.out.println(oauthURL.getAuthorizationURL());
   ```

4. 完成授权。
   开发者应该引导用户打开这个授权链接。当用户同意授权时，扣子编程会将页面重定向到开发者配置的回调地址，开发者可以获取这个 code，换取访问密钥。
   ```Java
   /*
   After the user clicks the authorization consent button, the coze web page will redirect
   to the redirect address configured in the authorization link and carry the authorization
   code and state parameters in the address via the query string.
   
   Get from the query of the redirect interface: query.get('code')
   * */
   String code = "mock code";
    
   /*
   After obtaining the code after redirection, the interface to exchange the code for a
   token can be invoked to generate the coze access_token of the authorized user.
   The developer should use code verifier returned by genOAuthURL() method
   * */
   OAuthToken resp = oauth.getAccessToken(code, redirectURI, oauthURL.getCodeVerifier());
   System.out.println(resp);
   
   // use the access token to init Coze client
   CozeAPI coze =
       new CozeAPI.Builder()
           .auth(new TokenAuth(resp.getAccessToken()))
           .baseURL(cozeAPIBase)
           .build();
   // When the token expires, you can also refresh and re-obtain the token
   resp = oauth.refreshToken(resp.getRefreshToken());
   ```


## 配置 OAuth 设备码授权流程 {#319c9071}
如果选择使用 OAuth 设备码方式完成授权，可参考以下流程及示例代码。完整的示例代码请参见 [DevicesOAuthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/DevicesOAuthExample.java)。

1. 创建 OAuth 应用。
   具体操作步骤可参考[OAuth 设备授权](/developer_guides/oauth_device_code)。成功创建 OAuth 应用后，你将获得客户端 ID。
2. 在代码中通过环境变量方式设置客户端 ID。
   ```Java
   public static void main(String[] args) {
       // 从环境变量获取设备授权的客户端ID，创建设备码类型OAuth应用时平台生成的唯一标识符
       String clientID = System.getenv("COZE_DEVICE_OAUTH_CLIENT_ID");
   
       // 创建设备授权客户端实例
       DeviceOAuthClient oauth =
           new DeviceOAuthClient.DeviceOAuthBuilder()
               .clientID(clientID)  // 传入客户端ID，即从环境变量获取的设备应用客户端ID
               // 设置授权服务器端点，由扣子编程固定提供的授权服务地址
               .baseURL(Consts.COZE_CN_BASE_URLCOZE_COM_BASE_URL)
               .build();
   ```

3. 通过 OAuth 设备码授权流程获得访问密钥。
   应用程序需要调用扣子编程 OpenAPI 生成设备代码，以获取 user_code 和 device_code。通过 user_code 生成授权链接，并引导用户打开该链接、填写 user_code、同意授权。应用程序调用扣子编程 OpenAPI，通过 device_code 生成访问密钥。
   如果用户尚未授权或拒绝了授权，接口将抛出异常并返回特定的错误代码。用户同意授权后，接口将成功并返回访问密钥。
   SDK 已经拼接了 URL，直接将 SDK 返回的 URL 交给用户打开即可。
   ```Java
   /*
    * 第一步：获取设备码和用户码
    */
   // 获取设备码响应对象，包含设备码、用户码、授权URL等信息
   DeviceAuthResp codeResp = oauth.getDeviceCode();
   System.out.println(codeResp);  // 打印设备码相关信息
   
   // 设备码，用于轮询访问令牌，从DeviceAuthResp对象的getDeviceCode()方法获取
   System.out.println(codeResp.getDeviceCode());
   
   // 用户需要访问的授权页面URL，用户输入user_code的页面地址，从DeviceAuthResp获取
   System.out.println(codeResp.getVerificationURL());
   ```

4. 应用程序还需要使用 device_code 来轮询扣子编程 OpenAPI 以获取访问密钥。
   Coze SDK for Java 已经封装了这部分代码，并处理了不同的返回错误代码。开发者只需要调用 get_access_token 即可。
   ```Java
   /*
    * 第二步：轮询获取访问令牌
    */
   try {
       // 轮询获取访问令牌，传入device_code和自动轮询标识（true为自动处理）
       OAuthToken resp = oauth.getAccessToken(codeResp.getDeviceCode(), true);
       System.out.println(resp);  // 用户授权成功后返回的访问令牌
   
       // 用access_token初始化Coze客户端
       CozeAPI coze =
           new CozeAPI.Builder()
               .auth(new TokenAuth(resp.getAccessToken()))  // 传入访问令牌
               .baseURL(cozeAPIBase)  // 设置OpenAPI服务端点
               .build();
   
       // 令牌过期时刷新，refresh_token从OAuthToken对象获取
       resp = oauth.refreshToken(resp.getRefreshToken());
   
   } catch (CozeAuthException e) {
       // 处理授权失败的情况
       if (AuthErrorCode.ACCESS_DENIED.equals(e.getCode())) {
           // 用户拒绝授权，需引导用户重新操作
           System.out.println("access denied");
       } else if (AuthErrorCode.EXPIRED_TOKEN.equals(e.getCode())) {
           // 令牌过期，需重新获取设备码并引导用户授权
           System.out.println("expired token");
       } else {
           e.printStackTrace();
       }
   } catch (Exception e) {
       e.printStackTrace();
   }
   ```


## 配置 OAuth JWT 授权流程 {#53e78d5f}
如果选择使用 OAuth JWT 方式完成授权，可参考以下流程及示例代码。完整的示例代码请参见 [JWTsOauthExample.java](https://github.com/coze-dev/coze-java/blob/main/example/src/main/java/example/auth/JWTOAuthExample.java)。

1. 创建 OAuth 应用并授权。
   具体操作步骤可参考[OAuth JWT 授权（开发者）](/developer_guides/oauth_jwt)。成功创建 OAuth 应用后，你将获得客户端 ID、公钥和私钥。你需要妥善保管公钥和私钥，以免数据泄露引发安全风险。
2. 在代码中通过环境变量方式设置客户端 ID、公钥和私钥。
   ```Java
   
   String jwtOauthClientID = System.getenv("COZE_JWT_OAUTH_CLIENT_ID");  // 从环境变量获取JWT授权的客户端ID，创建JWT类型OAuth应用时平台生成的唯一标识符
   String jwtOauthPrivateKey = System.getenv("COZE_JWT_OAUTH_PRIVATE_KEY");   // 从环境变量获取 OAuth 应用的私钥，用于签署JWT，可以在 OAuth 应用页面找到这个应用，在操作列单击编辑图标，进入配置页面下载私钥文件
   String jwtOauthPrivateKeyFilePath = System.getenv("COZE_JWT_OAUTH_PRIVATE_KEY_FILE_PATH");  // 从环境变量获取私钥文件路径，私钥文件在本地的存储路径，开发者自行指定
   String jwtOauthPublicKeyID = System.getenv("COZE_JWT_OAUTH_PUBLIC_KEY_ID");  // 从环境变量获取 OAuth 应用的公钥ID，可以在 OAuth 应用页面找到这个应用，在操作列单击编辑图标，进入配置页面查看公钥指纹。
   
   JWTOAuthClient oauth = null;
   try {
     jwtOauthPrivateKey =
         new String(
             Files.readAllBytes(Paths.get(jwtOauthPrivateKeyFilePath)), StandardCharsets.UTF_8);
   } catch (IOException e) {
     e.printStackTrace();
   }
   
   /*
   The jwt oauth type requires using private to be able to issue a jwt token, and through
   the jwt token, apply for an access_token from the coze service. The sdk encapsulates
   this procedure, and only needs to use get_access_token to obtain the access_token under
   the jwt oauth process.
   Generate the authorization token
   The default ttl is 900s, and developers can customize the expiration time, which can be
   set up to 24 hours at most.
   * */
   try {
     oauth =
         new JWTOAuthClient.JWTOAuthBuilder()
             .clientID(jwtOauthClientID)  //OAuth应用的客户端ID，创建 OAuth 应用时获取的客户端 ID。
             .privateKey(jwtOauthPrivateKey)   // OAuth 应用的私钥。
             .publicKey(jwtOauthPublicKeyID)  //OAuth 应用的公钥指纹。
             .baseURL(Consts.COZE_CN_BASE_URL)  //扣子 OpenAPI 的 Endpoint。
             .build();
   } catch (Exception e) {
     e.printStackTrace();
     return;
   }
   ```

3. 应用程序通过公钥和私钥签署 JWT，并通过扣子编程提供的 API 获取访问密钥。
   Coze SDK for Java 封装了这一过程，你只需要在OAuth JWT 流程中使用 get_access_token 来获取访问密钥即可。
   ```Java
   try {
     OAuthToken resp = oauth.getAccessToken();
     System.out.println(resp);
   } catch (Exception e) {
     e.printStackTrace();
   }
   /*
   The jwt oauth process does not support refreshing tokens. When the token expires,
   just directly call get_access_token to generate a new token.
   * */
   CozeAPI coze = new CozeAPI.Builder().auth(new JWTOAuth(oauth)).baseURL(Consts.COZE_CN_BASE_URL).build();
   // you can also specify the scope and session for it
   ```