List Access Tokens

List access tokens with optional filtering and pagination

Endpoint

GET /v1/access-tokens

List access tokens associated with your account. Returns metadata about the tokens (IDs, scopes, expiration) but not the actual token secrets.

This endpoint is not supported in s2-lite. Access token management is only available in S2 Cloud.

Query Parameters

prefix · string

Filter to access tokens whose IDs begin with this prefix. Use an empty string to match all tokens.

start_after · string

Filter to access tokens whose IDs lexicographically start after this string. Used for pagination.

limit · number · default: "1000"

Number of results to return, up to a maximum of 1000.

Response

access_tokens · array

List of access token information objects (up to 1000 items).

Show AccessTokenInfo object

id · string · required

Access token ID. Must be unique to the account and between 1 and 96 bytes in length.

expires_at · string

Expiration time in RFC 3339 format (e.g., 2027-01-01T00:00:00Z).

auto_prefix_streams · boolean

Whether stream names are automatically prefixed based on the stream-level scope.

scope · object · required

Access token scope defining permissions.

Show Scope properties

basins · object

Basin names allowed. Can be {"exact": "basin-name"} or {"prefix": "prefix-"}.

streams · object

Stream names allowed. Can be {"exact": "stream-name"} or {"prefix": "prefix-"}.

access_tokens · object

Token IDs allowed for token management operations. Can be {"exact": "token-id"} or {"prefix": "prefix-"}.

op_groups · object

Access permissions at operation group level.

Show Operation groups

account · object

Account-level access permissions with read and write boolean fields.

basin · object

Basin-level access permissions with read and write boolean fields.

stream · object

Stream-level access permissions with read and write boolean fields.

ops · array

List of specific operations allowed for the token. Union of ops and op_groups is used as the effective set of allowed operations.

has_more · boolean · required

Indicates whether there are more access tokens that match the criteria.

Example

cURL

curl -X GET "https://aws.s2.dev/v1/access-tokens?limit=10" \
  -H "Authorization: Bearer $S2_ACCESS_TOKEN"

200 OK

{
  "access_tokens": [
    {
      "id": "prod-api-token",
      "expires_at": "2027-01-01T00:00:00Z",
      "auto_prefix_streams": false,
      "scope": {
        "basins": {"prefix": "prod-"},
        "streams": {"prefix": ""},
        "op_groups": {
          "stream": {
            "read": true,
            "write": true
          }
        },
        "ops": []
      }
    },
    {
      "id": "prod-readonly-token",
      "expires_at": "2026-12-31T23:59:59Z",
      "auto_prefix_streams": false,
      "scope": {
        "basins": {"exact": "production"},
        "streams": {"prefix": "logs/"},
        "op_groups": {
          "stream": {
            "read": true,
            "write": false
          }
        },
        "ops": []
      }
    }
  ],
  "has_more": false
}

Pagination

To paginate through results:

1. Make an initial request with your desired limit
2. If has_more is true, make another request with start_after set to the last token ID from the previous response
3. Repeat until has_more is false

# First page
curl -X GET "https://aws.s2.dev/v1/access-tokens?limit=100" \
  -H "Authorization: Bearer $S2_ACCESS_TOKEN"

# Next page (if has_more: true)
curl -X GET "https://aws.s2.dev/v1/access-tokens?limit=100&start_after=last-token-id" \
  -H "Authorization: Bearer $S2_ACCESS_TOKEN"