Issue Access Token

Create a new access token with specified permissions

Endpoint

POST /v1/access-tokens

Issue a new access token with a specified ID, scope, and expiration. The response contains the actual token secret, which is only returned once and cannot be retrieved later.

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

Store the returned access_token value securely. You won’t be able to retrieve it again.

Request Body

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). If not set, the expiration will be set to that of the requestor’s token.

auto_prefix_streams · boolean · default: false

Namespace streams based on the configured stream-level scope, which must be a prefix. Stream name arguments will be automatically prefixed, and the prefix will be stripped when listing streams.

scope · object · required

Access token scope defining permissions.

Show Scope properties

scope.basins · object

Basin names allowed. Can be:

• {"exact": "basin-name"} - match only this specific basin
• {"prefix": "prefix-"} - match all basins starting with prefix
• {"prefix": ""} - match all basins (empty prefix)
• {"exact": ""} - match no basins

scope.streams · object

Stream names allowed. Same format as basins.

scope.access_tokens · object

Token IDs allowed for token management operations. Same format as basins.

scope.op_groups · object

Access permissions at operation group level.

Show Operation groups

scope.op_groups.account · object

Account-level access permissions.

Show Properties

read · boolean · default: false

Read permission for account operations (e.g., list basins, list tokens).

write · boolean · default: false

Write permission for account operations (e.g., create/delete basins, issue/revoke tokens).

scope.op_groups.basin · object

Basin-level access permissions (e.g., get config, reconfigure).

Show Properties

read · boolean · default: false

Read permission.

write · boolean · default: false

Write permission.

scope.op_groups.stream · object

Stream-level access permissions (e.g., read, append, trim).

Show Properties

read · boolean · default: false

Read permission for stream operations (read records, check tail, get config).

write · boolean · default: false

Write permission for stream operations (append, trim, create, delete, reconfigure).

scope.ops · array

List of specific operations allowed. A union of ops and op_groups is used as the effective set of allowed operations.

Available operations: list-basins, create-basin, delete-basin, reconfigure-basin, get-basin-config, issue-access-token, revoke-access-token, list-access-tokens, list-streams, create-stream, delete-stream, get-stream-config, reconfigure-stream, check-tail, append, read, trim, fence, account-metrics, basin-metrics, stream-metrics.

Response

access_token · string · required

The created access token. This is the only time the token secret will be returned.

Examples

cURL

curl -X POST "https://aws.s2.dev/v1/access-tokens" \
  -H "Authorization: Bearer $S2_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "app-backend-token",
    "expires_at": "2027-01-01T00:00:00Z",
    "scope": {
      "basins": {"prefix": ""},
      "streams": {"prefix": ""},
      "op_groups": {
        "stream": {
          "read": true,
          "write": true
        }
      }
    }
  }'

200 OK

{
  "access_token": "s2_AcTo01h8mCt9Qn..." 
}

Common Use Cases

Read-only token for specific streams

Create a token that can only read from streams with a specific prefix:

{
  "id": "analytics-readonly",
  "expires_at": "2026-12-31T23:59:59Z",
  "scope": {
    "basins": {"exact": "production"},
    "streams": {"prefix": "logs/"},
    "op_groups": {
      "stream": {
        "read": true,
        "write": false
      }
    }
  }
}

User-scoped token with auto-prefixing

Create a token for a specific user where all stream operations are automatically prefixed:

{
  "id": "user-1234-token",
  "expires_at": "2027-01-01T00:00:00Z",
  "auto_prefix_streams": true,
  "scope": {
    "basins": {"prefix": ""},
    "streams": {"prefix": "users/1234/"},
    "op_groups": {
      "stream": {
        "read": true,
        "write": true
      }
    }
  }
}

With auto_prefix_streams: true, when using this token:

• append("messages") → actually appends to "users/1234/messages"
• list_streams() → returns "messages" instead of "users/1234/messages"

Token with specific operations

Create a token with fine-grained permissions using the ops array:

{
  "id": "metrics-collector",
  "scope": {
    "basins": {"prefix": ""},
    "ops": ["account-metrics", "basin-metrics", "stream-metrics"]
  }
}

Security Best Practices

Principle of Least Privilege

Grant only the minimum permissions needed for the token’s intended use.

Set Expiration

Always set an expires_at time appropriate for the token’s use case.

Scope Narrowly

Use specific basin/stream prefixes or exact matches rather than allowing all resources.

Rotate Regularly

Implement token rotation for long-lived tokens.