Authenticate to an index#

Some Sysand indexes are access-restricted, for example a team’s private index on an internal network or a private forge. Use this guide when you have credentials for such an index (a token, or a username and password) and want sysand to use them. If you do not have credentials yet, ask whoever runs the index.

To create and configure a token for publishing to the Sysand Index at sysand.com, follow Create an API token instead.

Prerequisites#

  • sysand is installed.

  • The index URL and credentials for it.

Set the credential variables#

sysand reads credentials from environment variables: one variable holds a URL pattern that says where the credential applies, and one or two companion variables hold the credential itself. The TEAMIDX part below is a label of your choice that ties them together; the trailing ** makes the credential apply to everything under the index URL, so keep it.

The examples use https://index.example.org as the index URL; replace it with your index’s URL, and <token> with your credential.

Run in PowerShell:

PS> $env:SYSAND_CRED_TEAMIDX = "https://index.example.org/**"
PS> $env:SYSAND_CRED_TEAMIDX_BEARER_TOKEN = "<token>"

If the index uses a username and password instead of a token, keep the first line and replace the second:

PS> $env:SYSAND_CRED_TEAMIDX_BASIC_USER = "<username>"
PS> $env:SYSAND_CRED_TEAMIDX_BASIC_PASS = "<password>"

$ export SYSAND_CRED_TEAMIDX='https://index.example.org/**'
$ export SYSAND_CRED_TEAMIDX_BEARER_TOKEN='<token>'

If the index uses a username and password instead of a token, keep the first line and replace the second:

$ export SYSAND_CRED_TEAMIDX_BASIC_USER='<username>'
$ export SYSAND_CRED_TEAMIDX_BASIC_PASS='<password>'

$ export SYSAND_CRED_TEAMIDX='https://index.example.org/**'
$ export SYSAND_CRED_TEAMIDX_BEARER_TOKEN='<token>'

If the index uses a username and password instead of a token, keep the first line and replace the second:

$ export SYSAND_CRED_TEAMIDX_BASIC_USER='<username>'
$ export SYSAND_CRED_TEAMIDX_BASIC_PASS='<password>'

The variables last only for the current terminal session, so you will repeat this in each new terminal. In CI, set them through your CI system’s secret configuration (for example, masked CI variables) rather than plain environment settings, so the token stays out of job logs.

The full pattern syntax, and how sysand picks a credential for a URL, are described in Authentication.

Verify#

Ask sysand to describe a project that you know exists in the index. Pick one that exists only in this index: sysand also consults its default indexes, so a project that is also available publicly would resolve even with broken credentials. This only reads from the index and does not change anything locally:

$ sysand info --iri pkg:sysand/<publisher>/<name> --index https://index.example.org
Name: <name>
Publisher: <publisher>
Version: 1.0.0

If the project’s metadata is printed, authentication works, and any sysand command run in this terminal (sysand add, sysand sync, and so on) can authenticate the same way whenever you pass --index. To make the index your default so you can drop the --index option, follow Configure a different default index.

If you instead see no resolver was able to resolve the IRI, work through these checks (the message looks alarming but the cause is usually small):

  1. The variables are visible in the terminal you are running sysand from: check with printenv | grep SYSAND_CRED on macOS and Linux, or Get-ChildItem env:SYSAND_CRED* in PowerShell.

  2. The credential: a mistyped or expired token fails quietly, because some hosts report bad authentication as “not found” rather than “not allowed”.

  3. The URL pattern: the ** must still be at the end of the SYSAND_CRED_TEAMIDX value, and the pattern must match the index URL you pass to --index.

  4. The project: check the publisher and name spelling against what the index actually serves.

Running the command again with -v logs each URL sysand requests, which shows exactly which index it is trying and where the lookup stops.