Skip to main content
Every request to Enterprise Image Factory (factory.siderolabs.com) is authenticated — whether it comes from the web UI, a direct download, a registry pull, a PXE boot, or a Talos node pulling its installer image during an upgrade. Requests made outside a browser authenticate with an API token: a Talos node uses one to pull its installer image, a registry client such as docker uses one to pull an OCI artifact, and automation such as Terraform or a CI job uses one to create schematics and read security reports. This guide explains how to create an API token, where to use it, and how to rotate and revoke it. For a deeper look at how scopes, ownership, and lifetimes work, see Enterprise Image Factory API Tokens.

​
Authentication for Omni users

Omni holds its own API token and authenticates on your behalf. This covers the Omni UI, omnictl media download, and the installer images Omni instructs machines to pull. Create an API token only for work that happens outside Omni, such as:
  • A node managed with talosctl alone, rather than through Omni.
  • A CI job that downloads images or security reports.
  • Terraform, or another tool that creates schematics.
  • Any other direct call to the Enterprise Image Factory API.

​
Prerequisites

Before you begin, ensure you have the following:
  • An organization on Enterprise Image Factory, and the ability to log in to it. See Get access to an organization.
  • talosctl installed, to put a token in a Talos machine configuration.
  • curl, or a similar HTTP client, to call Enterprise Image Factory programmatically.

​
Get access to an organization

API tokens belong to an organization, so you need one before you can create a token. Your organization is provisioned as part of your Talos Enterprise Linux entitlement — either an Omni subscription or a standalone Talos Enterprise Linux support contract. If you cannot log in, contact support. Once your organization exists, log in at Enterprise Image Factory with your work email address. Enterprise Image Factory matches the email domain to your organization and sends you to your identity provider to complete the sign-in.

​
Create an API token

Tokens created here are recorded by Enterprise Image Factory, which makes them listable and revocable. These tokens count against a per-organization limit, so keep the number small and revoke tokens that are no longer in use. To create an API token:
  1. Log in to Enterprise Image Factory.
  2. Select Manage API Tokens to open the API Tokens page.
  3. Select + Create Token.
  4. Enter a descriptive Name.
  5. Enter a Lifetime, or leave the field empty to use the server default. Lifetimes are written in seconds (s), minutes (m), or hours (h).
  6. Select a Token actor to set the scopes your token carries. The form defaults to Talos. See Token actor profiles for more information.
  7. Select Create Token to save your token. Enterprise Image Factory then displays the following:
    • Identity: your organization ID, which is the username for HTTP Basic authentication.
    • Token: the API token.
    • Machine config patch: a RegistryAuthConfig document, shown for tokens that can pull images. See In a Talos machine configuration.
The token is displayed once. Enterprise Image Factory does not store it in a form it can show you again. Copy it to a secret manager before closing the dialog. If you lose a token, create a replacement and revoke the original.

​
Use an API token

Enterprise Image Factory accepts an API token in four places, depending on what is making the request.

​
In a Talos machine configuration

A Talos node pulls its installer image from Enterprise Image Factory at install and upgrade time. To allow that node to authenticate, embed a RegistryAuthConfig document into its machine configuration. This document is generated and displayed at token creation:
Update this document with your information and save it to a file. Next, run the following command to apply it to the node, replacing <node-ip> with the node’s address:
For the full range of ways to apply, patch, and stage machine configuration documents, see Edit Machine Configuration.

​
With an OCI or registry client

Registry clients such as docker and crane support only HTTP Basic authentication, so Enterprise Image Factory reads the token from the password field. Run the following command to log your registry client in to Enterprise Image Factory, replacing <organization-id> and <token> with your values:
The username is not checked, Enterprise Image Factory shows your organization ID as the identity to use, but any value works.
Once logged in, the client can pull installer images and other OCI artifacts from Enterprise Image Factory.

​
In an HTTP request

For clients that can set headers, send the token in an Authorization header using the Bearer scheme. Run the following command to download a schematic’s SBOM, replacing <token>, <schematic>, <version>, and <arch> with your values:

​
In a URL

Clients that cannot set a header, such as a browser following a link or an iPXE boot, pass the token as a ?token= query parameter:
The query parameter is read on GET and HEAD only, so it never authenticates a write. Tokens with token management scopes are refused. For the full details, see the Enterprise Image Factory authentication reference.
Proxy and CDN access logs record query strings, so a URL carrying a token discloses it. Give such a link the shortest lifetime that covers the task, and use a token that can be revoked.

​
Rotate an API token

Issuing a replacement token does not revoke the original. Both tokens remain valid until revoked or expired. To rotate an API token, create the replacement first, then revoke the original once the rollout is complete:
  1. Create a replacement token with the same actor profile. See Create an API token.
  2. Update every system that holds the original token. For nodes, patch each one with the new RegistryAuthConfig document before continuing.
  3. Confirm the replacement works. For nodes, this means confirming a pull from Enterprise Image Factory succeeds.
  4. Revoke the original token. See Revoke an API token.

​
Revoke an API token

Revoking a token removes the factory’s record of it, which takes the token out of circulation immediately across every replica. Revocation applies only to recorded tokens — short-lived tokens issued directly via the API are not recorded and cannot be revoked. To revoke an API token:
  1. Log in to Enterprise Image Factory.
  2. Select Manage API Tokens to open the API Tokens page.
  3. Find the token.
  4. Select Revoke on that row.
A node keeps working with a revoked token until its next pull from Enterprise Image Factory. That pull then fails, and the node cannot be upgraded or reinstalled until it holds a valid token.
Patch a node with a replacement token before revoking the token it is using. See Rotate an API token.