Skip to main content

Bearer token

BearerToken sends a token in a request header instead of signing the request with an AccessKey. It applies only to the product APIs that accept bearer authentication. It is not a general-purpose credential and is not a way to work around a missing AccessKey.

The token is static. ecctl cannot renew it, and there is no expiration field to check.

Configure with Alibaba Cloud CLI​

aliyun configure --mode BearerToken --profile bearer

ecctl configure --mode BearerToken is not supported. --mode accepts OAuth only, and an ecctl-native profile resolves only OAuth or a static credential. Put this profile in the compatible aliyun configuration file.

Configure with environment variables​

export ALIBABA_CLOUD_BEARER_TOKEN=<token>
export ALIBABA_CLOUD_BEARER_TOKEN_HEADER_KEY=<header-name>

The header variable is optional. In the environment chain this is the last source consulted, after an AccessKey pair, a complete OIDC set, ALIBABA_CLOUD_ECS_METADATA, and ALIBABA_CLOUD_CREDENTIALS_URI. Anything that resolves earlier wins.

Profile fields​

FieldRequiredNotes
modeNoBearerToken. Inferred when bearer_token is present
bearer_tokenYesFalls back to ALIBABA_CLOUD_BEARER_TOKEN when empty
bearer_token_header_keyNoDefaults to x-acs-bearer-token
{
  "name": "bearer",
  "mode": "BearerToken",
  "bearer_token": "...",
  "bearer_token_header_key": "x-acs-bearer-token",
  "region_id": "cn-hangzhou"
}

Set bearer_token_header_key only when the target API documents a different header name. The default is what most bearer-authenticated product APIs expect.

Scope limitation​

A bearer token is accepted only by APIs that support bearer authentication. An API that does not support it rejects the request at the service, in wording that comes from the service rather than from ecctl:

{
  "error": {
    "kind": "service",
    "code": "CloudAPIError",
    "message": "API call failed; see actions for details"
  },
  "actions": [
    {
      "action_name": "DescribeRegions",
      "code": "403, This signature type is not supported.",
      "message": "code: 403, This signature type is not supported."
    }
  ]
}

This response is the clearest signal that the mode is functioning as designed. The token was resolved, attached to the request, and delivered; the target API simply does not accept bearer authentication. Note the kind is service, not client: ecctl did not fail to produce a credential.

This signature type is not supported is not a configuration problem to fix in the profile. It means the operation you called is not a bearer-authenticated operation. Use a signing mode such as OAuth, AK, or RAM role ARN for general resource commands, and reserve BearerToken for the API that asked for it.

Verify​

ecctl --profile bearer configure get

configure get has no key for the bearer token. The keys it accepts are region, access-key-id, access-key-secret, security-token, lang, output, and telemetry.enabled, so asking for bearer_token returns a client error with code UnknownConfigKey. Read the value back from the configuration file instead, and only when you deliberately need it:

grep bearer_token ~/.aliyun/config.json

Because there is no local validity check, the only real verification is a request to an API that accepts bearer authentication. A 403 from an unrelated API tells you nothing about whether the token is valid.