Session URLs Commands¶

The site session-urls command group provides functionality to create and verify session-scoped URLs for temporary, path-limited access to a site.

Overview¶

Session URLs allow you to: - Grant temporary access to a site without sharing the master token directly - Restrict access to read-only or read/write operations - Scope access to a specific path subtree - Attach an identifier describing who or what is using the session - Validate a session URL before using it in automation or integrations

What are Session URLs?¶

A session URL is a temporary site URL that carries session credentials and metadata controlled by the site API: - Bound to a site, not just a single file - Includes an expiration time - Carries a permission level - Can be restricted to a path such as /data/ or /reports/2026/ - Includes an identifier for auditing and operational tracking

Example:

https://sites.ecmwf.int/myspace/mysite/?session=eyJ...

Global Flags¶

--debug, -d, --verbose - Show debug information
--insecure, -k - Skip TLS certificate verification
--force, -f, -y, --yes - Force operations without prompting
--output, -o - Output format: json, yaml, or table

Commands¶

`sitesctl site session-urls create`¶

Create a session-scoped URL for a site.

Usage:

sitesctl site --space <space> --name <name> session-urls create --identifier <label> [flags]

Flags:

--identifier (required) - Mandatory label identifying who or what will use this session
Use something stable and descriptive such as ci-pipeline, data-sync-job, or temporary-share
This value is returned during verification and is useful for auditing
--duration - Session lifetime in seconds
Default: 86400 (24 hours)
After this period, the session URL becomes invalid
--permission - Access permission level
Values: r (read-only) or rw (read/write)
Default: r
--path - Optional path scope for the session URL
Defaults to the full site scope when omitted
Use / for the whole site explicitly
Use a narrower prefix such as /data/ to limit what the session can access

Examples:

# Create a read-only session URL for the whole site
sitesctl site --space myspace --name mysite \
  session-urls create \
  --identifier ci-pipeline

# Create a 1-hour session URL
sitesctl site --space myspace --name mysite \
  session-urls create \
  --identifier report-job \
  --duration 3600

# Restrict the session to a specific subtree
sitesctl site --space myspace --name mysite \
  session-urls create \
  --identifier data-reader \
  --path /data/

# Create a read/write session URL for uploads under /incoming/
sitesctl site --space myspace --name mysite \
  session-urls create \
  --identifier ingest-worker \
  --permission rw \
  --path /incoming/ \
  --duration 7200

# Save the session URL to a variable
session_url=$(sitesctl site --space myspace --name mysite \
  session-urls create \
  --identifier nightly-sync \
  --path /exports/ \
  --output json | jq -r '.url')

Common Duration Values:

Duration	Seconds	Use Case
1 hour	3600	CI/CD job or one-off task
6 hours	21600	Work session
24 hours	86400	Default daily access
7 days	604800	Temporary collaboration

Output: - Session URL

Use Cases: - Temporary automation access to a site subtree - Delegated upload sessions for ingestion jobs - Short-lived integration credentials for external tools - Operational debugging with clearly labeled sessions

`sitesctl site session-urls verify`¶

Verify a session URL and inspect the session payload.

Usage:

sitesctl site --space <space> --name <name> session-urls verify --url <session-url> [flags]

Flags: - --url (required) - Session URL to verify - --request-path - Optional request URI to validate against the session path scope

Examples:

# Verify a session URL
sitesctl site --space myspace --name mysite \
  session-urls verify \
  --url "$session_url"

# Verify a session URL against a specific request path
sitesctl site --space myspace --name mysite \
  session-urls verify \
  --url "$session_url" \
  --request-path /data/report.csv

# Verify with JSON output for scripting
sitesctl site --space myspace --name mysite \
  session-urls verify \
  --url "$session_url" \
  --output json

What it does: - Validates that the session URL is still accepted by the site API - Returns the decoded session payload when available - Optionally checks whether a specific request path is allowed by the session scope

Output: - Path scope - Permission level - Identifier - Expiration timestamp - Error details if the session URL is invalid

Use Cases: - Check whether a generated session is still valid - Confirm that a path restriction matches the intended workflow - Troubleshoot automation failures caused by expired or narrow-scoped sessions - Inspect session metadata for auditing

How Session URLs Work¶

Creation Process¶

Input: Identifier + duration + permission + optional path scope
Server-side creation: The site API issues a session URL tied to those constraints
Output: A session URL that can be used until expiration

Verification Process¶

Input: Session URL and optionally a request path
Validation: The site API checks whether the session is valid and not expired
Scope check: If --request-path is provided, the API validates that path against the session scope
Result: The CLI reports success or prints the returned payload or error response

Security Properties¶

Expiration: The session becomes invalid automatically after the configured duration
Scoped access: The session can be limited to a path prefix
Permission control: Read-only and read/write modes are explicit
Traceability: The identifier helps distinguish sessions operationally

Comparison: Session URLs vs Signed URLs vs HTTP Access Tokens¶

Feature	Session URLs	Signed URLs	HTTP Access Tokens
Scope	Site or path prefix	Single file/directory URL	Entire site
Authentication	Embedded session credential	Embedded signature	Token in header/parameter
Path restriction	Yes	Implicit in signed URL target	No path restriction
Permission	`r` or `rw`	`r` or `rw`	`r` or `rw`
Expiration	Per session	Per URL	Per token
Best For	Temporary site workflows	Sharing a specific resource	General API automation

When to use Session URLs: - Automation needs temporary access to part of a site - You want a labeled session with a clear permission and path boundary - You need more flexibility than a single signed file URL

When to use Signed URLs: - You are sharing a specific file or directory target - The recipient just needs a simple direct URL

When to use HTTP Access Tokens: - You need general API-style access to the whole site - Your client already handles token-based authentication cleanly

Common Workflows¶

Temporary Read Access for a Job¶

#!/bin/bash

space="myspace"
name="mysite"

session_url=$(sitesctl site --space "$space" --name "$name" \
  session-urls create \
  --identifier batch-reader \
  --path /exports/ \
  --duration 3600 \
  --output json | jq -r '.url')

echo "Session URL ready: $session_url"

Validate Path Scope Before Running a Workflow¶

#!/bin/bash

sitesctl site --space myspace --name mysite \
  session-urls verify \
  --url "$session_url" \
  --request-path /exports/daily/report.csv

Generate a Read/Write Session for Ingestion¶

#!/bin/bash

sitesctl site --space myspace --name mysite \
  session-urls create \
  --identifier ingest-worker \
  --permission rw \
  --path /incoming/ \
  --duration 7200

Troubleshooting¶

Session URL Expired¶

Problem: The session URL is rejected by the API.

Solutions: - Re-run session-urls verify to confirm the current state - Generate a new session URL with a suitable duration - Shorten job startup delays if sessions expire before use

Request Path Not Allowed¶

Problem: Verification fails when --request-path is supplied.

Solutions: - Check the original --path used at creation time - Ensure the request path is inside the allowed prefix - Create a new session URL with a broader path scope if needed

Invalid Session URL¶

Problem: Verification returns an error response.

Solutions: - Confirm the URL was copied completely - Verify the session belongs to the expected site - Regenerate the session URL and test again

Integration Examples¶

Bash Script¶

session_url=$(sitesctl site --space myspace --name mysite \
  session-urls create \
  --identifier sync-worker \
  --path /exports/ \
  --duration 3600 \
  --output json | jq -r '.url')

sitesctl site --space myspace --name mysite \
  session-urls verify \
  --url "$session_url" \
  --request-path /exports/file.csv

Python Script¶

import json
import subprocess


def create_session_url(space, name, identifier, path="/", duration=3600):
    cmd = [
        "sitesctl", "site",
        "--space", space,
        "--name", name,
        "session-urls", "create",
        "--identifier", identifier,
        "--path", path,
        "--duration", str(duration),
        "--output", "json",
    ]
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
    return json.loads(result.stdout)["url"]


session_url = create_session_url("myspace", "mysite", "etl-job", "/exports/")
print(session_url)