canonical: https://jentic.com/apis/maif.local/otoroshi

# Maif Otoroshi Admin API

Otoroshi is an open-source layer of lightweight API management developed by MAIF. The Admin API exposes 102 endpoints to manage service descriptors, API keys, service groups, JWT verifiers, authentication modules, scripts, data exporter configs, and TLS certificates on an Otoroshi gateway. It is the control-plane interface for routing, rate limiting, quota enforcement, and runtime configuration of the reverse proxy that sits in front of microservices.

## For AI agents

Configure an Otoroshi reverse proxy through 102 admin endpoints - register services, mint API keys with quotas, manage JWT verifiers, and update routing live without restarting the gateway.

## Scope

Does not handle traffic forwarding, TLS termination, or runtime request routing - use for Otoroshi configuration management only.

## Capabilities

- Register service descriptors that route traffic from a public domain to upstream targets
- Issue API keys scoped to a service or group and enforce per-key quota limits
- Configure global JWT verifiers and authentication module configs for protected services
- Compile and deploy custom request transformer scripts against a running gateway
- Manage TLS certificates and data exporter configs without redeploying Otoroshi

## Use cases

### Microservice Gateway Provisioning

Onboard a new microservice behind Otoroshi by creating a service descriptor that maps a public host to upstream targets, attaching it to a service group, and minting scoped API keys for downstream consumers. The Admin API exposes service, group, and apikey resources so the entire onboarding can run from a CI pipeline rather than the Otoroshi UI. A typical onboarding takes minutes once the descriptor template is parameterised.

Example prompt: Create a service descriptor named orders-api routing orders.example.com to two upstream targets, attach it to the production group, then create an API key with a 5000-call daily quota.

### API Key Quota Management

Operate an internal API marketplace by issuing per-consumer API keys with read-only quota visibility. Each key sits inside a service or group, and the quotas endpoint reports remaining call budget so an agent can renew, throttle, or revoke keys before consumers hit hard limits. Resetting a quota is a single DELETE call against the quotas resource.

Example prompt: Fetch the quota state for clientId abc123 on serviceId orders-api, and if remaining calls are below 100, reset the quota and notify the owning team.

### JWT and Auth Module Lifecycle

Manage authentication configuration centrally by maintaining global JWT verifiers and auth module configs through the API. Verifiers can be created, patched with a JSON diff, or deleted as identity providers rotate keys, so an agent can reconcile gateway auth with an upstream IdP without operator intervention.

Example prompt: List all global JWT verifiers, find the one named auth0-prod, and PATCH it to add a new audience value of orders-api.

### Agent-Managed Gateway Operations

An AI agent invoked through Jentic can run end-to-end Otoroshi operations such as adding a target to a service, compiling a transformer script, and verifying that the new configuration is live. The agent receives basic-auth credentials from your Jentic One instance and never sees raw secrets, which makes Otoroshi safe to expose to autonomous workflows that touch production routing.

Example prompt: Add a new upstream target with weight 20 to serviceId orders-api, then GET the targets list and confirm the addition before exiting.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/services` | List all service descriptors |
| POST | `/api/services` | Create a new service descriptor |
| POST | `/api/groups/{groupId}/apikeys` | Mint an API key for a service group |
| GET | `/api/services/{serviceId}/apikeys/{clientId}/quotas` | Read the current quota state for an API key |
| POST | `/api/verifiers` | Create a global JWT verifier |
| POST | `/api/scripts/_compile` | Compile a transformer script |
| POST | `/api/services/{serviceId}/targets` | Add an upstream target to a service descriptor |

## Key resources

- **Services** — Service descriptors that map public hosts to upstream targets and apply plugins
- **API Keys** — Per-consumer credentials with quota and group scoping
- **Service Groups** — Logical groupings of services for shared API keys and policies
- **JWT Verifiers** — Global JWT validation configurations applied to services
- **Auth Modules** — Authentication backend configurations for SSO and OIDC
- **Scripts** — Custom request and response transformer code compiled and deployed at runtime
- **Data Exporter Configs** — Outbound metric and event exporter configurations

## Why Jentic

- **Setup:** Wiring the Otoroshi Admin API by hand means encoding basic-auth credentials on every request and coordinating them across service descriptor, API-key, verifier, and script-compilation paths. Through Jentic you install once, import the Otoroshi Admin API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Otoroshi puts the service id in the URL path (`/api/services/{serviceId}/...`), so a rule can pin your agent to reading API-key quotas and managing targets for one service and nothing else. You choose the operations it may call, so broad ones like creating a service descriptor or minting a group API key are not included unless you add them.
- **Credential handling:** Your Otoroshi credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an Otoroshi API key' or 'read a service's quota state', and Jentic returns the matching Otoroshi operation with its input schema so the agent calls the right endpoint without browsing the Otoroshi docs.

## Related APIs

- **Gravitee API Management** — Open-source API gateway and management platform with a similar admin model to Otoroshi.
- **Cloudflare API** — Edge network and DNS provider that often sits in front of an Otoroshi instance.

## FAQ

### What authentication does the Otoroshi Admin API use?

The Otoroshi Admin API uses HTTP Basic authentication via the otoroshi_auth scheme. Requests must include an Authorization header with a base64-encoded admin client_id and client_secret pair issued from the Otoroshi UI. Through Jentic, the credentials are stored encrypted in the vault and injected at execution time, so the agent never sees the raw secret.

### Can I manage API key quotas with the Otoroshi Admin API?

Yes. GET `/api/services/{serviceId}/apikeys/{clientId}/quotas` returns the current consumption state for a key, and DELETE on the same path resets the counter. The same pattern is available under `/api/groups/{groupId}/apikeys/{clientId}/quotas` for keys scoped to a service group.

### What are the rate limits for the Otoroshi Admin API?

The Admin API itself does not publish a rate limit - Otoroshi is a self-hosted gateway, so admin throughput is bounded by the resources of the instance you operate. If you put the admin endpoint behind another Otoroshi service, you can apply your own quota policy to it.

### How do I register a new service through Jentic?

Search Jentic for "register a service in otoroshi" to load the POST `/api/services` operation, then call execute with a service descriptor JSON body that names the upstream targets, host, and group. A template is available from GET `/new/service` to seed the descriptor.

### Is the Otoroshi Admin API free to use?

Yes. Otoroshi is open-source software released by MAIF under the Apache 2.0 licence. There is no per-call fee - you only pay for the infrastructure that runs the gateway.

### Can I deploy custom transformer scripts through the Admin API?

Yes. POST `/api/scripts/_compile` compiles a script source against the running Otoroshi version and returns errors if it does not type-check. Once compiled, POST `/api/scripts` persists the script and it can be referenced from a service descriptor for request or response transformation.

### Can I limit what my agent is allowed to do with the Otoroshi Admin API?

Yes. Because you run Jentic One yourself, your own rules decide which Otoroshi operations and credentials the agent may use. Since Otoroshi puts the service id in the URL path (for example `/api/services/{serviceId}/apikeys/{clientId}/quotas`), you can pin the agent to reading API-key quotas and managing targets for a single service and nothing else. Broad operations such as creating a service descriptor with POST `/api/services` or minting a group API key stay out of reach unless you explicitly add them.