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

# Blob S3 凭证

> 通过 GET /v1/s3/credentials 获取你的 API key 对应的 S3 访问密钥对，以便在 Blob Storage 上使用 aws-cli、boto3、rclone 和 AWS SDK。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
</ParamField>

S3 凭证会返回 S3 工具用于为发往 [S3 网关](/zh/blob-reference/s3-compatibility)的请求签名的访问密钥对。该密钥对**由调用此路由的 API key 派生**：再次调用会返回同一对密钥，撤销、重新生成 key 或 key 过期都会对密钥对产生同样的效果。没有其他需要轮换或撤销的东西。

请使用拥有 `blob:read` 或 `blob:write` 的 API key 调用它。拥有 `blob:read` 时密钥对可以读取，拥有 `blob:write` 时可以写入，如 `access` 字段所示。

<Warning>`secret_access_key` 提供与 API key 相同的访问权限。请像保管 key 本身一样保管它。</Warning>

<Tip>只要 API key 不变，密钥对就不会变。获取一次后将其保存在你的密钥管理器或环境变量中：不要在每次应用启动时都调用此路由。</Tip>

### 速率限制

<Note>每个账户每小时 10 次请求（`RATE_LIMITED`，429）。</Note>

### 响应

<ResponseField name="status" type="string">
  成功为 "success"，否则为 "error"。
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="展开对象">
    <ResponseField name="access_key_id" type="string">
      访问密钥 id（`SQ2_...`）。
    </ResponseField>

    <ResponseField name="secret_access_key" type="string">
      秘密访问密钥。
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      `https://s3-blob.squarecloud.app`
    </ResponseField>

    <ResponseField name="region" type="string">
      `auto`
    </ResponseField>

    <ResponseField name="buckets" type="string[]">
      你账户的 bucket：`public`、`private` 和 `legacy`。
    </ResponseField>

    <ResponseField name="access" type="object">
      `read` 和 `write`，各为 `true` 或 `false`，取决于 key 的 scope。
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601 | null">
      API key（因而也是该密钥对）的过期时间。不会过期时为 `null`。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://blob.squarecloud.app/v1/s3/credentials' \
    --header 'Authorization: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "access_key_id": "SQ2_3155597145698959364_k7Hq2mX9",
      "secret_access_key": "vR8nLq2Wz5Tc1Yb7Hs0Kd4Jf6Gm3Pa9Xe",
      "endpoint": "https://s3-blob.squarecloud.app",
      "region": "auto",
      "buckets": ["public", "private", "legacy"],
      "access": { "read": true, "write": true },
      "expires_at": null
    }
  }
  ```
</ResponseExample>

### 错误

| 代码                   | HTTP | 触发情况                                     |
| -------------------- | ---- | ---------------------------------------- |
| `API_KEY_REQUIRED`   | 400  | 使用控制台会话调用。请使用 API key。                   |
| `LEGACY_API_KEY`     | 400  | 该 key 使用无法为 S3 请求签名的旧格式。请创建一个新的 API key。 |
| `INVALID_CREDENTIAL` | 401  | 无法验证该 API key。                           |
| `MISSING_SCOPE`      | 403  | 该 key 既没有 `blob:read` 也没有 `blob:write`。  |
| `RATE_LIMITED`       | 429  | 一小时内超过 10 次请求。                           |