multi-router.aidocs

Machine Identity

BindingsEnterprise

Naming the callers that may use an issuer's tokens, and the routers each may reach.

A binding connects a caller, identified by the subject in its tokens, to the routers it may use. Bindings belong to an organization and are managed under Machine identity bindings in that organization's settings; bindings on the account's own routers are on the Bindings tab in Account Settings. An organization creates bindings on issuers it is authorized for.

Creating a binding

Engineering · org_3Fh8Wq2LdK

Org Settings

Machine identity bindings

Which callers may reach which routers in Engineering, and what they are allowed to do.

Callers connect to https://api.multi-router.ai Copy

New binding

Identify the caller, then choose what it may reach.

Issuer
Token audience
mr-aud_PtYgjmUhBel31iEl2hpChYgCfrL1spNxnyVmihA_2O7Copy

Put this in the pod spec. Tokens from this issuer are only accepted if they carry it.

Routers this binding may use
Payments classifieropenai / openai/gpt-5-mini · rt_8Mc5Jx3VbN
Add router

With one router no routing header is sent — just a base URL and a credential.

What this binding allows
CancelCreate binding
system:serviceaccount:billingprefixkubernetes service accountProduction cluster · 2 routers · inference
A new binding for a Kubernetes service account, with one router. Select to enlarge.

A binding is created in six steps:

  1. In the organization, open Settings, then Machine identity, and select Add binding.
  2. Choose the Issuer, and the Caller type: Kubernetes service account or CI job.
  3. Choose the Match, This exact subject or Anything under a prefix, and enter the Subject.
  4. Under Routers this binding may use, add one or more routers.
  5. Under What this binding allows, Send inference requests is always granted; turn on List available models when the caller lists models.
  6. Select Create binding.

Subjects

The subject is the token's sub value, which names the caller. Its form depends on the platform:

PlatformSubject example
Kubernetessystem:serviceaccount:payments:api
GitHub Actions, a branchrepo:example-co/billing:ref:refs/heads/main
GitHub Actions, a job with an environmentrepo:example-co/billing:environment:production
GitHub Actions, a pull requestrepo:example-co/billing:pull_request

Subjects are case sensitive, up to 700 bytes, with no surrounding spaces. A GitHub job that declares an environment uses the environment form, so a binding for a branch matches jobs without one; an organization that customizes GitHub's subject format uses its own form.

Matching

A binding matches subjects in one of two ways:

MatchMatchesAvailable on
This exact subjectOne subject.Every issuer.
Anything under a prefixThe prefix itself, and subjects that continue it after a colon.Cluster issuers and GitHub Actions.

Prefixes follow these rules:

IssuerPrefix ruleExample
ClusterStops after the namespace, and covers every service account in it.system:serviceaccount:payments
GitHub ActionsStarts with a complete owner and repository, and can go deeper.repo:example-co/billing

Prefixes match at the colon between parts, so repo:example-co/billing covers repo:example-co/billing:ref:refs/heads/main and leaves repo:example-co/billing-v2 out. Prefixes are literal text, without wildcards such as *. When several bindings in an organization match a subject, an exact binding wins, then the longest prefix, and the binding chosen applies even when it is disabled.

Routers

A binding names 1 to 100 routers of its organization, by router id rather than alias. With one router, a caller sends only the base URL and its token, and requests go to that router. With several, each request names its router in the model field as multi-router/rt_9Hk3Ws7PzQ or in the x-mr-router header; when both are present, the model field wins.

Permissions

A binding allows inference, and optionally listing models:

PermissionScopeAllows
Send inference requestsinferenceRequests to the binding's routers. Always on.
List available modelsmodels:readGET /v1/models, listing the models of the binding's router, or of the router named in x-mr-router when it has several.

Bindings across organizations

A subject belongs to one organization: a binding that overlaps another organization's binding, as the same subject or one prefix inside another, is refused with a message naming the organization. Within one organization, overlapping bindings are allowed and resolved by the matching order above, and each subject and match pair is bound once.

Kubernetes UID changes

For an exact Kubernetes binding, Multi-Router remembers the service account's unique id from its first token. When a later token carries a different id, the binding shows UID changed, meaning the service account was deleted and recreated, or the name now belongs to something else. Requests keep being served; review the binding and disable it if the change was unexpected.

Editing and deleting

Editing a binding changes everything except its issuer. Binding enabled turns it off and on, and deleting it stops the caller from authenticating. Changes take effect across Multi-Router within about a minute. An issuer holds up to 1,000 bindings.

IssuersKubernetes
Was this helpful?