How authentication works#

Credentials matter in two distinct situations when using sysand:

  • Publishing to the official Sysand Index. The index at sysand.com is public (browsing and installing projects requires no credentials), but sysand publish requires authentication. In supported CI environments it uses trusted publishing by default; elsewhere it uses a bearer token. See Create an API token.

  • Reading from an access-restricted location. Any Sysand index or project download location may require authentication, for example a self-hosted index on an internal network. Then sysand needs credentials just to fetch projects; see Authenticate to an index for the setup steps.

The rest of this page explains the moving parts: where credentials live, how they are scoped, what login validation means, and how publishing uses them. For exact variable names, URL glob behavior, and command output, see Authentication and the sysand auth command pages.

Sysand currently supports:

  • HTTP(S) using (fixed) bearer tokens (used by, for example, the Sysand Index and private GitLab projects read through the repository files API), storable with sysand auth login or supplied through environment variables

  • HTTP(S) using the basic access authentication scheme, supplied through environment variables only

  • Git, for projects fetched from git repositories, using your existing git setup (SSH keys, credential helpers). Sysand has no separate git credential configuration; see Request behavior.

Two credential sources#

A credential can be a stored credential, written once by sysand auth login into the operating system’s keyring and reused across terminals and reboots, or an environment credential in SYSAND_CRED_* variables, which lasts as long as the shell or CI job that sets it. Stored credentials are the convenient path on a desktop; environment variables are the path in CI, on hosts without a keyring, and for username/password indexes.

The two coexist by precedence, not merging: for any URL both could serve, the environment credential wins. That direction is deliberate. An environment variable is visible, local, and easy to unset, so it is safe to let it override; a hidden store silently overriding your shell would be much harder to debug. It also means a CI job can inject its own token without touching whatever a developer has stored. sysand auth status shows both sources in one view and marks stored entries that are shadowed.

Credential scope#

Every credential, stored or environment, applies only to URLs matching its pattern. This matters because a single project can use more than one network location: the official Sysand Index, a private index, direct archive URLs, or Git repositories. URL-scoped credentials let one setup hold credentials for several locations without sending every credential to every server.

For environment credentials you write the pattern yourself. For a stored login, sysand auth login derives the patterns from the index URL and from the roots the index’s discovery configuration advertises, and prints them. The derived patterns are a snapshot from login time: if the index operator later reconfigures the index to point elsewhere, the stored credential does not silently follow; requests to the moved location stop matching, and you log in again to accept the new layout. This is a security boundary: it prevents a changed (or tampered-with) index configuration from redirecting your stored token to a host you never agreed to send it to.

What login validation tells you#

sysand auth login does not just store the token; it first exercises it against each surface the index has and records what accepted it:

  • validated (read) or validated (api): a real surface accepted the token.

  • stored, not validated: nothing could exercise it (a public index, or one that was offline or unreachable), so the token is stored without a verdict rather than refused.

A bad token is refused only when a surface actually rejected it, which on an index with public reads and an API, such as sysand.com, means the API check catches a mistyped or expired token at login instead of at publish time. For the full probing rules and every outcome, see Login validation.

How publishing uses credentials#

sysand publish talks to an index in two legs. First it reads the index’s discovery configuration to find the API root; this is an ordinary read, unauthenticated for a public index, using the regular credential selection for a private one. Then it uploads to the API root, and that leg is different: it always sends a bearer token proactively, selected by the same precedence (environment first, then stored credentials), and fails up front when none matches. In supported CI environments, trusted publishing replaces the bearer token entirely.

This split explains two things you may observe: a token that was validated (read) on a private index can still be refused for publishing (reading and publishing are different permissions), and a publish failure names where the offending token came from, because the fix differs between rotating an environment variable and re-running sysand auth login.