API tokens

API tokens authenticate package-index API requests, including release uploads from the sysand client. This page lists the token types, limits, and upload authorization behavior enforced by Sysand Index.

For the step-by-step token creation workflow, see Create an API token. To store a created token in the sysand client, use sysand auth login. For trusted publishing OIDC upload tokens, see Trusted publishing.

Token types

Token type	Prefix	Scope
Account API token	sysand_u_	Uses the account owner’s permissions. It can upload to existing projects the account can maintain and can create new projects in namespaces where the account is allowed to publish.
Project API token	sysand_p_	Scoped to one existing project. It can upload releases only for that project.
Trusted publishing upload token	sysand_oidc_	Short-lived token issued by OIDC token exchange for one matched trusted publisher and project.

The API authentication layer accepts bearer tokens whose value starts with one of those prefixes. Other token prefixes are rejected for package-index API authentication.

Creation limits

Account and project API tokens use the same creation rules:

Rule	Value
Name length	3-100 characters
Name characters	Letters, numbers, spaces, underscores, hyphens, and slashes
Name boundary	Must start and end with a letter or number
Expiration	1-365 days
Default expiration	90 days
Active-token cap	5 non-expired account tokens per user, and 5 non-expired project tokens per project by default
Creation rate limit	5 token creation attempts per user per hour by default, shared between account and project token creation

Creating an account or project API token requires recent reauthentication. Stale sessions are sent through the account reauthentication flow before the token creation request is replayed.

Visibility and storage

The full plaintext token is shown only once, immediately after creation. Sysand Index stores a token hash and a display prefix, not the full plaintext token.

Responses that show a newly created plaintext token are marked Cache-Control: no-store.

Token lists show metadata such as the token name, display prefix, creation time, expiration time, and last-used time where applicable.

Revocation and expiry

Expired tokens are rejected during API authentication. Revoked account and project tokens are deleted and can no longer be used.

Project API tokens created by a project member are automatically revoked if that member is removed from the project or if the creator account is deleted.

Upload authorization

Release uploads authenticate with Authorization: Bearer <token>.

Upload target	Account API token	Project API token	Trusted publishing upload token
Existing project	Allowed when the account has effective project Owner or Maintainer access.	Allowed only for the token’s project.	Allowed only for the matched trusted-publishing project.
New project in a personal namespace	Allowed only in the account owner’s namespace.	Not allowed.	Not allowed.
New project in an organization namespace	Allowed when the account is an organization Owner or Manager.	Not allowed.	Not allowed.

For existing projects, effective project access can come from direct project membership or from an organization team with project access.

Token identity

Clients can ask which identity a token belongs to, without uploading anything. The endpoint is:

GET /api/v1/whoami

It authenticates with Authorization: Bearer <token> and answers:

{
  "subject": { "type": "user", "name": "alice" },
  "token": {
    "name": "laptop",
    "prefix": "sysand_u_1a2b3c4d",
    "expires_at": "2026-10-01T00:00:00Z"
  }
}

subject.type is user, project, or oidc. subject.name is the username for an account token, <namespace>/<project> for a project token, and the matched publisher identity for a trusted publishing upload token. token.name is the label given at creation, and is null for trusted publishing upload tokens, which carry no label. token.prefix is the display prefix, never the secret.

The endpoint is read-only: it never creates, refreshes, or consumes a token. It does update the token’s last-used timestamp for account and project tokens. Because it reports token validity before authorization, it is rate limited per client IP before authentication, at 30 requests per minute by default; requests over the limit get 429 with a Retry-After header.

This is the endpoint the sysand client uses for sysand auth whoami and for validating a token during sysand auth login. An index advertises it by setting api_root in its discovery configuration; an index without an API root has no identity endpoint.

Authentication failures

API requests fail with 401 Unauthorized when the bearer token is missing, uses an unsupported prefix, does not match a stored token hash, has expired, or is a trusted publishing upload token that has already been consumed.

Upload requests fail with 403 Forbidden when the token is valid but is not authorized for the target namespace or project.