Prepare your endpoints for a security assessment

Last updated on September 18, 2026

Overview​

For every endpoint you want tested, Extend Security Assessment needs to know whether it requires authentication and which IAM permission it enforces. It discovers this automatically by calling your running Extend app — you don't fill this in by hand for every endpoint — but it can only do so if your app declares its permissions in a way it can read.

Requirement: a reachable OpenAPI spec​

Your Extend Service Extension app must expose a reachable Swagger v2 (OpenAPI 2.0) spec, typically served at <YourServiceURL>/apidocs/api.json — the default for apps built from AccelByte's service extension templates. This is a hard requirement: if Extend Security Assessment can't fetch your spec, it can't list your endpoints or accept a request at all.

For more information about this spec, see Extend App UI: Codegen specs.

How permissions are discovered, in order​

  1. OpenAPI x-required-permission extension. For every protected operation, Extend Security Assessment looks for a custom OpenAPI extension field on that operation:

    "x-required-permission": "ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE]"

    If your service is built from one of AccelByte's Service Extension templates (available for Go, C#, Java, and Python), you get this for free by declaring the permission on the RPC in your .proto file. Every template shares the same gRPC proto definition, so protoc-gen-openapiv2 bakes the permission into the generated Swagger spec automatically, regardless of which language template you used:

    rpc CreateOrUpdateGuildProgress (CreateOrUpdateGuildProgressRequest) returns (CreateOrUpdateGuildProgressResponse) {
      option (permission.action)   = CREATE;
      option (permission.resource) = "ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD";
      option (google.api.http) = {
        post: "/v1/admin/namespace/{namespace}/progress"
        body: "*"
      };
      option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
        security: { security_requirement: { key: "Bearer" value: {} } }
        extensions: {
          key: "x-required-permission"
          value { string_value: "ADMIN:NAMESPACE:{namespace}:CLOUDSAVE:RECORD [CREATE]" }
        }
      };
    }

    If you're not using one of these templates, add the x-required-permission extension to the equivalent operation in whatever tool generates your OpenAPI spec, using the format RESOURCE [ACTION] (for example, ADMIN:NAMESPACE:{namespace}:SEASON [UPDATE]).

  2. gRPC server reflection. Extend Security Assessment also independently queries your app's gRPC server reflection service and reads the permission.resource / permission.action method options directly off the proto method — the same options shown in the snippet above. This only works if reflection is registered on your service (AccelByte's Service Extension templates register it by default). If it isn't, it simply continues without this source.

  3. Precedence. Extend Security Assessment reads both sources for every endpoint. If an endpoint's permission is declared in both places, the OpenAPI x-required-permission value wins; the gRPC reflection value only takes effect when the OpenAPI spec doesn't declare a permission for that operation. If neither source declares a permission for an endpoint, and both a spec and gRPC reflection were successfully reached, it treats that endpoint as intentionally unauthenticated — no prompt, no warning.

  4. Manual override. If a permission genuinely can't be discovered (no gRPC reflection and no x-required-permission in the spec), you can enter the permission string yourself when selecting endpoints for the request. Extend Security Assessment validates the format — it must be namespace-scoped and can't use wildcards — but it can't validate the value against what your app actually enforces at runtime. An incorrect value can still cause the test cases to under- or over-scope what they check, so enter it carefully.

tip

Fix permissions in your code rather than relying on the manual override. Declaring x-required-permission (or the equivalent proto options) on a protected endpoint is a one-time change — once it's in your code, that endpoint's permission is discovered automatically and correctly for every future security assessment.

Last updated on
On this page