multi-router.aidocs

Machine Identity

OverviewEnterprise

Letting workloads call Multi-Router with the identity their own platform gives them, in place of a stored API key.

Machine identity lets an application authenticate to Multi-Router with a short-lived token its own platform issues, such as a Kubernetes service account token or a GitHub Actions OIDC token, instead of an API key stored as a secret. The platform signs the token, Multi-Router checks the signature and the token's subject on every request, and the caller reaches only the routers its binding allows. The platform's own short-lived tokens are the only credential, so there is nothing for the team to store or rotate.

Issuers and bindings

Machine identity has two parts, each set on the Machine identity page in Settings:

PartBelongs toPurpose
IssuerThe accountA platform that signs tokens, such as an EKS cluster or GitHub Actions, registered by its issuer URL. Each issuer gets a token audience that its tokens must carry.
BindingAn organizationA caller, identified by the token's subject such as system:serviceaccount:payments:api, and the routers it may use.

An issuer is registered once for the account and authorized for the organizations that may bind callers to it. Each organization then creates bindings for its own callers and routers.

How a request is authenticated

Every machine request is checked in four steps:

  1. The workload asks its platform for a token for the issuer's token audience, and sends it as Authorization: Bearer.
  2. Multi-Router finds the issuer by the audience, and checks the token's issuer, signature, expiry and lifetime.
  3. It finds the binding that matches the token's subject, and checks that the binding allows the router the request names.
  4. The request is served by that router, and Traffic records the issuer, subject and binding.

Machine identity and API keys

Machine identity and API keys both authenticate callers, for different kinds of caller:

API keyMachine identity
CredentialA long-lived sk-mr- key stored as a secretA short-lived token the platform issues on demand
RotationReplace the keyAutomatic, as the platform issues new tokens
ReachChosen scopes and routersInference, and optionally listing models, on the binding's routers
Identity in TrafficThe key idThe issuer, subject and binding
Suited toScripts, tools, and applications on other platformsWorkloads in Kubernetes clusters and CI jobs

Supported platforms

Machine identity works with any issuer that publishes an OpenID Connect discovery document and signing keys at a public https address:

PlatformIssuer type in the dashboardSubjects
Amazon EKS clusterAWS EKS clusterKubernetes service accounts, exact or by namespace
Google GKE clusterGoogle GKE clusterKubernetes service accounts, exact or by namespace
Azure AKS cluster, with its OIDC issuer turned onAzure AKS clusterKubernetes service accounts, exact or by namespace
GitHub ActionsGitHub ActionsWorkflow runs, exact or by repository
GitLab.comGitLab.comExact CI job subjects
CircleCICircleCIExact CI job subjects
Google AccountsGoogle AccountsExact subjects
Any other OpenID Connect issuerCustom issuerExact subjects

The other pages in Machine Identity cover each part in detail:

PageCovers
IssuersRegistering issuers, token audiences, key fetching and health.
BindingsSubjects, matching, routers and permissions.
KubernetesCalling Multi-Router from a pod with a service account token.
GitHub ActionsCalling Multi-Router from a workflow with an OIDC token.
Calling Multi-RouterToken requirements, router selection, limits and Traffic.
TroubleshootingAuthentication errors, with causes and fixes.
Managing AgentsIssuers
Was this helpful?