API Key 与来源白名单

API Key 让第三方程序和网页不登录也能读取「API Key」级别的服务与地图方案。Key 属于工作空间，可以设置过期时间与来源白名单，随时撤销。

创建、复制与撤销

• 位置：控制台「管理 → 工作空间」，打开工作空间，切到「API Key」页签。只有该工作空间的管理者能管理 Key，其他人看到「只有该工作空间的管理者可以管理 API Key」。
• 新建：点「新建 API Key」，填写：
  • 名称（必填，最多 64 个字符）；
  • 过期时间（不填则永不过期，必须晚于当前时间）；
  • 域名白名单、IP 白名单（每行一个，见下文）。
• 只显示一次：创建成功后对话框显示完整的 Key 与复制按钮。关闭后无法再次查看，平台只保存它的摘要；列表中只显示前 10 个字符用于辨认。丢失时撤销后重新创建。
• 撤销：列表每行的「撤销」，确认后最长约 30 秒内全部失效，撤销不可恢复。
• Key 形如 gb_xxx…：以 gb_ 开头，共 46 个字符。

一个 Key 能访问什么

• 本工作空间内「公开」与「API Key」级别的服务和地图方案（公开的本来就不需要 Key）。
• 不能访问本工作空间的「私有」服务，也不能访问其他工作空间的任何非公开服务。
• 只能读，不能写：要素编辑接口必须登录，见访问级别。
• 想知道某个 Key 能访问哪些服务，可以用 JS SDK 的 client.services.list()（调用服务目录接口，最多返回 1000 条）。

两种传递方式

方式	写法	何时用
请求头	X-GeoBridge-Token: gb_xxx…	服务端程序优先用这种：Key 不出现在地址里，不会进入代理、CDN 的访问日志与浏览器历史
查询参数	地址后加 token=gb_xxx…	无法自定义请求头的场景：<img>、OpenLayers 的 XYZ 与 WMS 图层、QGIS 等 GIS 软件；或跨域、瓦片量大的网页（见下文）

# 请求头
curl -H 'X-GeoBridge-Token: gb_xxx…' 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/VectorTileServer/tiles.json'
# 查询参数
curl 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/VectorTileServer/tiles.json?token=gb_xxx…'

• 两处都带时以查询参数为准。表单体或 JSON 体里的 token 不认。
• 浏览器跨域使用请求头时，浏览器会对每个不同的地址先发一次 OPTIONS 预检。瓦片很多、对加载速度敏感的页面，用查询参数更快，代价是 Key 会出现在地址里。
• JS SDK 默认用请求头（keyTransport: 'header'），可改为 'query'；对不能加请求头的库，用 client.withKey(url) 给地址补上 token。SDK 只把 Key 发往你配置的平台地址，不会发给其他主机。

哪些响应会自动带上 Key

请求在查询参数里带了 Key 时，以下响应中指向本服务的地址会自动追加 token=…，客户端按响应继续请求即可，无需自己拼接：

• 矢量切片服务的样式（resources/styles）中的数据源、字形与雪碧图地址，以及 tiles.json 中的瓦片地址；
• OGC 服务的文档：WMS、WFS、WMTS、WCS 能力文档中的操作地址、图例地址、瓦片模板与翻页链接，OGC API 文档中的全部链接，TMS 文档之间的链接（TMS 每级瓦片的地址除外），见 OGC 服务概览；
• 地图方案公开样式地址返回的样式中，指向本平台服务的地址。

只用请求头传 Key 时，这些地址不改写，需要客户端给每个请求加请求头（MapLibre 用 transformRequest）。指向其他主机的地址（如第三方底图）不会被改写，Key 不会泄露给它们。矢量切片的地址改写只认小写的 token 参数（OGC 服务不区分大小写）。

来源白名单

名单	条目格式	按什么匹配
域名白名单	主机名，如 example.com；或 *.example.com（只匹配子域名，不匹配 example.com 本身）	请求的来源：先看 Origin 请求头，没有时看 Referer 的主机名；两者都没有即不通过
IP 白名单	IPv4 或 IPv6 地址，或 CIDR 网段，如 203.0.113.5、10.0.0.0/8；不接受带前导零的写法，不做域名解析	发起请求的客户端 IP

• 两个名单都设置时，必须同时满足。名单不为空而没有条目匹配时一律拒绝，错误码 TOKEN_INVALID。
• 不区分大小写，重复条目自动去掉。
• 域名白名单只防浏览器：Origin、Referer 由客户端发送，非浏览器程序可以随意伪造。要限制第三方服务器，请用 IP 白名单。
• 在网页里使用的 Key 对访问者是可见的（打开开发者工具即可看到）。请给这类 Key 配上域名白名单，并只把确实要对外的服务设为「API Key」级别。
• 在线沙箱的运行页不带可识别的来源域名，设置了域名白名单的 Key 在沙箱里一定会被拒绝，见在线沙箱。
• 本地部署的平台放在反向代理之后时，需要管理员按部署说明配置转发客户端地址，否则 IP 白名单无法正确匹配。

跨域（CORS）

• 公开数据地址（服务地址、地图方案样式地址、字体、雪碧图、图标）允许任何网页跨域读取：响应带 Access-Control-Allow-Origin: *，允许 X-GeoBridge-Token 请求头，预检结果缓存 1 天。错误响应同样带这些头，跨域页面能读到错误码。
• 跨域请求不带登录状态：平台不允许跨域携带凭据，其他网站的页面只能匿名或用 API Key 读取。用户登录了控制台，也不会让别的网站借他的身份读取私有服务。
• 管理接口（控制台使用的接口）不提供跨域访问，只能由平台自己的页面调用。