multi-router.aidocs

API Reference

Machine IdentityEnterprise

Registering identity issuers, granting them to organizations, and binding workload subjects to routers and scopes.

The machine identity endpoints manage issuers, the identity providers whose tokens workloads present, and bindings, which let a workload subject from an issuer call chosen routers with chosen scopes. Issuers belong to the account and are granted to organizations; their writes need a key of the account organization. Bindings belong to the organization of the key. See Machine Identity.

MethodPathDescriptionScope
GET/v1/machine-identity/issuersList issuers visible to the organization. Paginated.machine_identity:read
POST/v1/machine-identity/issuersRegister an issuer from name and issuer_url. Returns 201. Accepts dry_run and an Idempotency-Key.machine_identity:write
GET/v1/machine-identity/issuers/{id}Get one issuer, with its key-fetch health.machine_identity:read
PATCH/v1/machine-identity/issuers/{id}Change name, enabled, max_token_lifetime_seconds, on_key_fetch_failure and tenancy. Accepts dry_run.machine_identity:write
DELETE/v1/machine-identity/issuers/{id}Delete an issuer with no bindings or grants. Accepts dry_run.machine_identity:delete
POST/v1/machine-identity/issuers/{id}/organizationsGrant the issuer to the organization_id sent. Accepts dry_run.machine_identity:write
DELETE/v1/machine-identity/issuers/{id}/organizations/{organization_id}Remove a grant. Accepts dry_run.machine_identity:delete
GET/v1/machine-identity/bindingsList the organization's bindings. Paginated.machine_identity:read
POST/v1/machine-identity/bindingsCreate a binding. Returns 201. Accepts dry_run and an Idempotency-Key.machine_identity:write
GET/v1/machine-identity/bindings/{id}Get one binding.machine_identity:read
PATCH/v1/machine-identity/bindings/{id}Change router_ids, scopes and enabled. Accepts dry_run.machine_identity:write
DELETE/v1/machine-identity/bindings/{id}Delete a binding. Accepts dry_run.machine_identity:delete

An issuer create can also set max_token_lifetime_seconds, on_key_fetch_failure (serve_stale or fail_closed), enabled and organization_ids. Multi-Router reads the issuer's discovery document to find its jwks_uri and tenancy; a dry run returns that preview without saving. A binding has issuer_id, subject, subject_type (ci or kubernetes_service_account), subject_match (exact or prefix), router_ids, scopes and an optional enabled.

Bind a GitHub Actions workflow to a routerbash
curl -X POST https://api.multi-router.ai/v1/machine-identity/bindings \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_id": "mii_2Kd7Wq9LmP",
    "subject": "repo:acme/app:ref:refs/heads/main",
    "subject_type": "ci",
    "subject_match": "exact",
    "router_ids": ["rt_9Hk3Ws7PzQ"],
    "scopes": ["inference"]
  }'
CodeStatusMeaning
invalid_parameter400A field is invalid. The field names it.
issuer_discovery_failed400The issuer's discovery document or keys could not be read.
account_organization_required403An issuer write uses a key of a named organization.
not_found404No issuer or binding has that id.
issuer_not_granted409The issuer is not granted to the organization of the binding.
duplicate_binding409A binding with the same issuer, subject and match type already exists, in this or another organization.
cross_organization_precedence409The binding overlaps another organization's binding for the same issuer.
issuer_in_use409A delete names an issuer that still has grants or bindings.
organization_in_use409A grant removal names an organization that still has bindings to the issuer.
organization_already_granted409The issuer is already granted to the organization.
account_issuer_limit409The account has its maximum number of issuers.
issuer_grant_limit409The issuer has its maximum number of grants.
issuer_binding_limit409The issuer has its maximum number of bindings.
use_sub_collection400An issuer PATCH sends organization_ids. Grants change through /v1/machine-identity/issuers/{id}/organizations.
SSO
Was this helpful?