Authentication¶

Before you can manage sites, upload files, or call any API, you need to prove who you are. The library provides an Authenticator object that handles this for you. There are four ways to create one — choose the one that fits your workflow.

Overview¶

All four methods produce an Authenticator instance that you pass to SitesClient or SiteContentManagement.

Username & password¶

Authenticate with your ECMWF username and password. Behind the scenes the library exchanges them for a short-lived JWT via ECMWF's OpenID Connect endpoint.

from sites.sdk.sites import Authenticator

authenticator = Authenticator.from_credentials(
    username='your_username',
    password='your_password'
)

Retrieve the JWT to reuse later:

token = authenticator.get_token()
print(token)
# eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

You can pass this token to Authenticator.from_token() to avoid re-fetching it on every run.

Bearer token¶

Every site has a unique, long-lived bearer token that is generated when the site is created. You can find it in the site's configuration on the Sites platform. This token type is recommended for automation because it avoids handling your personal credentials in scripts.

from sites.sdk.sites import Authenticator

authenticator = Authenticator.from_token(
    token='ed19f076328b925e59bc05d36624cb9e05413fa150fb316d61bbcc5588968bee'
)

Note: This token is scoped to a single site and is best used when constructing a SiteContentManagement object (via site.get_content_manager()). It cannot be used for hub-level operations like listing all sites or creating new ones — use credentials or a JWT for those.

Base64-encoded credentials¶

If you want to store your credentials in a config file without plain-text passwords, you can encode them as base64 strings and restore an Authenticator from that encoding later.

from sites.sdk.sites import Authenticator

# Step 1: encode credentials from an existing authenticator
auth = Authenticator.from_credentials(username='myuser', password='mypassword')
encoded = auth.get_credentials_base64()
print(encoded)
# dXNlcm5hbWU=.cGFzc3dvcmQ=   (base64(username).base64(password))

# Step 2: in a later session, restore the authenticator from the encoded string
authenticator = Authenticator.from_credentials_base64(credentials=encoded)

Security note: Base64 is an encoding, not encryption. This method obscures credentials but does not protect them from anyone with access to the encoded string. For sensitive environments, prefer environment variables or a secrets manager.

Environment variables¶

Set credentials as environment variables before running your script. The values can be plain text or base64-encoded — the library detects the encoding automatically.

Set environment variables (shell):

export SITES_AUTHENTICATOR_USERNAME="myuser"
export SITES_AUTHENTICATOR_PASSWORD="mypassword"

# Or base64-encoded:
export SITES_AUTHENTICATOR_USERNAME="bXl1c2Vy"
export SITES_AUTHENTICATOR_PASSWORD="bXlwYXNzd29yZA=="

Use in Python:

from sites.sdk.sites import Authenticator

authenticator = Authenticator.from_environment_variables()

This is the recommended approach when running automated scripts in CI/CD environments, because your credentials never appear in source code.

Passing the authenticator to a client¶

Once you have an Authenticator, pass it wherever it is needed:

from sites.sdk import SitesClient
from sites.sdk.sites import Site, Authenticator

# Hub-level operations (list sites, create sites, etc.)
auth = Authenticator.from_credentials(username='myuser', password='mypassword')
client = SitesClient(authenticator=auth)

# Site content operations — use the site's unique bearer token
site = Site.from_space_and_name(space='docs', name='mysite')
site_auth = Authenticator.from_token(token='<site_bearer_token>')
content_manager = site.get_content_manager(authenticator=site_auth)

Useful helper methods¶

What's next?¶

• Site Management — create and configure your first site
• Content Management — upload files to your site
• Access Tokens — generate per-site tokens for automation