SView Help Center
English (US)

获取AccessToken(个人身份登录)

Author: sviewngts Last Updated: 2026-08-25 16:26
前提:该个人账号已经由集成业务方导入到企业看图系统中
实际开发中注意点:
  • 不要等到 Token 完全过期再刷新,建议提前 10% 左右的时间(比如 12 小时的话,提前 1 小时)就用 refresh_token 刷新,避免请求被拦截。
  • refresh_token 本身也有有效期,一般比 access_token 长得多(比如 30 天),过期后就只能让用户重新授权登录了。
接口名 POST: /auth/oauth2/token

 

入参:(body传值)

application/x-www-form-urlencoded
是否必传 默认值 描述 备注
mobile 是 -   使用integrationId进行登录 其中integrationId需要替换成实际值
grant_type 是 mobile   固定值:mobile
scope 是 server   固定值:server
入参:(Header传值)
Authorization 是 - 客户端标识 格式:Basic base64(clientId:clientSecret)
Content-Type 是 - Content-Type application/x-www-form-urlencoded
回参示例:(application/json)

 

{
    "tenant_id": "tenant_id",
    "sub": "username",
    "iss": "https://xxx.com",
    "active": true,
    "token_type": "Bearer",
    "client_id": "sviewweb",
    "access_token": "b185d0c9-c3ee-xxxx-8b53-78fb0c0ea8f6",
    "refresh_token": "IAIK__8LVShcxxxxxxxxxx-4zcv2Y8-GqWleKt9KJWQ3tumaDWWWskECNCiQB2xxxxxxxxxcIUQsOshAp2bGJifhyR_SyUPcMb63XhLPKOaQMd-QkmP4O23fwRL",
    "aud": [
        "client_id"
    ],
    "license": "https://xxx.com",
    "nbf": 1779782030.897981181,
    "user_id": "18373xxxxxxx698049",
    "scope": [
        "server"
    ],
    "exp": 1779825230.897981181,
    "expires_in": 43199, //token有效期(秒)
    "iat": 1779782030.897981181,
    "jti": "cbc9537a-f2de-4aec-881c-599adf52b12d",
    "username": "xxxxxxx"
}
package com.hoteam.sview.demo;

import cn.hutool.core.codec.Base64;
import cn.hutool.core.util.CharsetUtil;
import cn.hutool.core.util.StrUtil;
import cn.hutool.http.ContentType;
import cn.hutool.http.Header;
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.http.HttpStatus;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;
import lombok.extern.slf4j.Slf4j;

/**
 * 获取 AccessToken(个人身份登录 / mobile 模式)
 * <p>
 * grant_type 固定为 mobile,mobile 字段使用 IntegrationId 进行登录,
 * 格式:INTEGRATION@{integrationId},IntegrationId为该成员在外部平台的唯一ID,
 * 在导入用户时由集成方管理员指定。
 */
@Slf4j
public class OAuth2TokenIntegrationDemo {

    /** 鉴权接口地址,部署时替换为实际 gateway 地址 */
    private static final String TOKEN_URL = "http://your-host/auth/oauth2/token";

    /** 客户端 ID,可在系统中查看 */
    private static final String CLIENT_ID = "your_client_id";

    /** 客户端密钥,可在系统中查看 */
    private static final String CLIENT_SECRET = "your_client_secret";

    /**
     * 通过个人身份(IntegrationId)登录获取 AccessToken
     *
     * @param integrationId 集成业务方维护的 IntegrationId
     * @return access_token;获取失败返回 null
     */
    public static String getAccessTokenByIntegration(String integrationId) {
        if (StrUtil.isBlank(integrationId)) {
            log.warn("integrationId 不能为空");
            return null;
        }

        // mobile 字段拼接规则:INTEGRATION@{integrationId}
        String mobile = "INTEGRATION@" + integrationId;

        // Authorization: Basic base64(clientId:clientSecret)
        String basicAuth = "Basic " + Base64.encode(
                (CLIENT_ID + ":" + CLIENT_SECRET).getBytes(CharsetUtil.CHARSET_UTF_8));

        HttpRequest request = HttpRequest.post(TOKEN_URL)
                .header(Header.AUTHORIZATION, basicAuth)
                .header(Header.CONTENT_TYPE, ContentType.FORM_URLENCODED.getValue())
                .form("grant_type", "mobile")
                .form("mobile", mobile)
                .form("scope", "server")
                .timeout(10_000);

        // 添加公共 Header(tenant-id、deviceId、deviceModel、deviceType、lang 等)
        CommonHeaderUtil.withCommonHeaders(request);

        try (HttpResponse response = request.execute()) {
            int status = response.getStatus();
            String body = response.body();
            log.info("获取 AccessToken(个人身份登录)响应: status=[{}], body=[{}]", status, body);

            if (status == HttpStatus.HTTP_UNAUTHORIZED) {
                log.warn("认证失败,请检查 clientId / clientSecret / integrationId, body=[{}]", body);
                return null;
            }
            if (!response.isOk() || StrUtil.isBlank(body)) {
                log.warn("获取 AccessToken 响应异常: status=[{}], body=[{}]", status, body);
                return null;
            }

            JSONObject json = JSONUtil.parseObj(body);
            String accessToken = json.getStr("access_token");
            String refreshToken = json.getStr("refresh_token");
            Integer expiresIn = json.getInt("expires_in");

            if (StrUtil.isBlank(accessToken)) {
                log.warn("响应中未提取到 access_token, body=[{}]", body);
                return null;
            }

            log.info("登录成功 username=[{}], tenant_id=[{}], expires_in=[{}]s, refresh_token=[{}]",
                    username, tenantId, expiresIn, refreshToken);
            return accessToken;
        } catch (Exception e) {
            log.error("获取 OAuth2 Token(个人身份登录)接口异常", e);
            return null;
        }
    }
}