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.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/machine-identity/issuers | List issuers visible to the organization. Paginated. | machine_identity:read |
| POST | /v1/machine-identity/issuers | Register 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}/organizations | Grant 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/bindings | List the organization's bindings. Paginated. | machine_identity:read |
| POST | /v1/machine-identity/bindings | Create 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.
| Code | Status | Meaning |
|---|---|---|
invalid_parameter | 400 | A field is invalid. The field names it. |
issuer_discovery_failed | 400 | The issuer's discovery document or keys could not be read. |
account_organization_required | 403 | An issuer write uses a key of a named organization. |
not_found | 404 | No issuer or binding has that id. |
issuer_not_granted | 409 | The issuer is not granted to the organization of the binding. |
duplicate_binding | 409 | A binding with the same issuer, subject and match type already exists, in this or another organization. |
cross_organization_precedence | 409 | The binding overlaps another organization's binding for the same issuer. |
issuer_in_use | 409 | A delete names an issuer that still has grants or bindings. |
organization_in_use | 409 | A grant removal names an organization that still has bindings to the issuer. |
organization_already_granted | 409 | The issuer is already granted to the organization. |
account_issuer_limit | 409 | The account has its maximum number of issuers. |
issuer_grant_limit | 409 | The issuer has its maximum number of grants. |
issuer_binding_limit | 409 | The issuer has its maximum number of bindings. |
use_sub_collection | 400 | An issuer PATCH sends organization_ids. Grants change through /v1/machine-identity/issuers/{id}/organizations. |