Service groups

Overview

A service group is a logical grouping of services (routes, APIs) whose primary purpose is to define the authorization scope of API keys. Without service groups, you would need to authorize each API key on every individual route it should access. Service groups solve this problem by letting you bundle related routes together and authorize an API key on the group as a whole, granting it access to all routes within that group.

How service groups interact with API keys

An API key has an authorizedEntities field that lists the entities it is allowed to access. When a service group identifier appears in this list, the API key is automatically authorized on every route that belongs to that group. A single API key can be authorized on multiple service groups, and a single route can belong to multiple groups, providing a flexible many-to-many authorization model.

This means credentials can span multiple services without being duplicated: rather than creating separate API keys for each route, you create one key and authorize it on the appropriate groups.

Service groups vs. organizations and teams

It is important not to confuse service groups with organizations (tenants) and teams. They serve different purposes:

• Organizations and teams are multi-tenancy and admin access control constructs. They determine which users can view and manage entities in the Otoroshi admin UI, and they partition the configuration space into logical boundaries.
• Service groups are a runtime authorization construct. They define which API keys can call which routes when traffic flows through the gateway. They have no effect on admin UI access.

When to use service groups

Use service groups when multiple routes should share the same API key authorization. Typical examples include:

• A set of payment-related APIs that should all accept the same client credentials.
• A collection of internal microservices that a single upstream gateway needs to reach.
• A versioned API surface (v1, v2) where a consumer key should work across all versions.

UI page

You can find all service groups here

Properties

Property	Type	Description
id	string	Unique identifier of the group
name	string	Display name of the group
description	string	Description of the group
tags	array of string	Tags for categorization
metadata	object	Key/value metadata

How it works

1. Create a group with a meaningful name (e.g., "Payment APIs", "Public APIs")
2. Assign routes to the group by adding the group ID to a route's groups field
3. Authorize API keys on the group using the API key's authorizedEntities field

When an API key is authorized on a group, it automatically has access to all routes that belong to that group. This simplifies API key management significantly when you have many routes that share the same access control requirements.

JSON example

{
  "id": "group_payment_apis",
  "name": "Payment APIs",
  "description": "All payment-related API routes",
  "metadata": {
    "department": "finance"
  },
  "tags": ["payment", "finance"]
}

Authorizing an API key on a group

In the API key entity, reference the group in authorizedEntities:

{
  "clientId": "my-api-key-id",
  "clientSecret": "my-api-key-secret",
  "clientName": "Payment service key",
  "authorizedEntities": ["group_payment_apis"]
}

Adding a route to a group

In the route entity, add the group ID to the groups array:

{
  "id": "route_process_payment",
  "name": "Process payment",
  "groups": ["group_payment_apis"],
  "frontend": { "..." : "..." },
  "backend": { "..." : "..." },
  "plugins": { "..." : "..." }
}

Admin API

GET    /api/groups           # List all service groups
POST   /api/groups           # Create a service group
GET    /api/groups/:id       # Get a service group
PUT    /api/groups/:id       # Update a service group
DELETE /api/groups/:id       # Delete a service group
PATCH  /api/groups/:id       # Partially update a service group

When a service group is deleted, the resources associated are not deleted. The group reference on those resources will become invalid (empty).

Related entities

• Routes - Routes reference groups in their groups field
• API Keys - API keys reference groups in their authorizedEntities field
• APIs - APIs also create virtual groups automatically for their routes