> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Test a Federation Configuration End-to-End > Resolves the candidate federation configuration against a synthetic user AND dispatches a one-shot smoke probe (the caller-supplied test_script, e.g. "SELECT 1") to the agent identified in the request body. Persisted state is never read or written: the entire candidate connection + federation pair lives in the body. Returns the resolved principal, the env-var keys that were injected (values are never returned), and the agent-side stdout/stderr of the probe. Success requires both phases to succeed. ## OpenAPI ````yaml https://use.hoop.dev/api/openapiv3.json post /federation/test openapi: 3.0.3 info: contact: email: help@hoop.dev name: Help url: https://help.hoop.dev description: >- Hoop.dev is an access gateway for databases and servers with an API for packet manipulation license: name: MIT url: https://opensource.org/license/mit termsOfService: https://hoop.dev/docs/legal/tos title: Hoop Api version: 1.115.0 servers: - url: https://use.hoop.dev/api security: [] tags: - description: > Hoop implements Oauth2 and OIDC protocol to authenticate users in the system. To obtain a valid access token users need to authenticate in their own identity provider which is generated as a JSON response to the endpoint `http(s)://use.hoop.dev/api/login`. The identity provider them redirects the user to the callback endpoint containing the access token. The recommended approach of obtaining an access token is by visiting the Webapp main's page or using the **Hoop command line**. Example: ```sh hoop config create --api-url https://use.hoop.dev # save the token after authenticating at $HOME/.hoop/config.toml hoop login # show token information hoop config view --raw ``` With an access token you could use any HTTP client to interact with the documented endpoints. The token must be sent through the `Authorization` header. Example: ```sh # obtain the current configuration of the server curl https://use.hoop.dev/api/serverinfo -H "Authorization: Bearer $ACCESS_TOKEN" ``` name: Authentication - description: > Users are active and assigned to the default organization when they signup. A user could be set to an inactive state preventing it from accessing the platform, however it’s recommended to manage the state of users in the identity provider. - The `sub` claim is used as the main identifier of the user in the platform. - The profile of the user is derived from the id_token claims `email` and `name`. When a user authenticates for the first time, it performs an automatic signup that persist the profile claims along with it’s unique identifier. ​ ### Groups Groups allows defining who may access or interact with certain resources. - For connection resources it’s possible to define which groups has access to a specific connection, this is enforced when the Access Control feature is enabled. - For review resources, it’s possible to define which groups are allowed to approve an execution, this is enforced when the Review feature is enabled. > This resource could be managed manually via Webapp or propagated by the identity provider via ID Token. In this mode, groups are sync when a user performs a login. ### Roles - The `admin` group is a special role that grants full access to all resources This role should be granted to users that are responsible for managing the Gateway. All other users are regular, meaning that they can access their own resources and interact with connections. name: User Management - name: Machine Identities - description: Routes used to manage and obtain information about the runtime server. name: Server Management - description: Features available in the gateway. See also **Plugin** resources. name: Features - description: >- Proxy manager endpoints controls how clients connect via gRPC in the gateway. These endpoints are meant to be used when a client is initialized via `hoop proxy-manager`. name: Proxy Manager - name: Connections - name: Agents - name: Runbooks - name: Guard Rails - name: Reviews - name: Sessions - name: Organization Management - name: Reports - description: > Security audit log API. Only users in the **admin** group can access these endpoints. Audit log entries record security-relevant events (who performed an action, when, on which resource, and whether it succeeded). Use the list endpoint with filters to query by actor, resource type, action, outcome, or date range. Results are paginated and ordered by `created_at` descending. name: Audit Logs paths: /federation/test: post: tags: - Federation summary: Test a Federation Configuration End-to-End description: >- Resolves the candidate federation configuration against a synthetic user AND dispatches a one-shot smoke probe (the caller-supplied test_script, e.g. "SELECT 1") to the agent identified in the request body. Persisted state is never read or written: the entire candidate connection + federation pair lives in the body. Returns the resolved principal, the env-var keys that were injected (values are never returned), and the agent-side stdout/stderr of the probe. Success requires both phases to succeed. requestBody: content: application/json: schema: $ref: '#/components/schemas/openapi.FederationTestRequest' description: The request body resource required: true x-originalParamName: request responses: '200': content: application/json: schema: $ref: '#/components/schemas/openapi.FederationTestResponse' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Bad Request '500': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Internal Server Error components: schemas: openapi.FederationTestRequest: properties: config: allOf: - $ref: '#/components/schemas/openapi.ConnectionFederationConfig' description: >- Config is the candidate federation configuration to test. Required. Carries the plaintext admin_credentials_json the resolver will use to authenticate; the value never reaches persistence on this endpoint. connection: allOf: - $ref: '#/components/schemas/openapi.FederationTestConnection' description: |- Connection is the candidate connection the probe runs against. Required. The endpoint does NOT look up a persisted connection by name/id — the caller supplies the agent, command, script and envs directly so a wizard draft can be exercised before persistence. user_email: description: UserEmail is the synthetic user to resolve. Required. example: alice@example.com type: string user_id: description: >- UserID is the synthetic user ID. Optional; defaults to a deterministic UUID derived from UserEmail. example: 00000000-0000-0000-0000-000000000001 type: string required: - config - connection - user_email type: object openapi.FederationTestResponse: properties: admin_principal: description: AdminPrincipal is the impersonator identity (e.g. admin SA email). example: hoop-admin@proj.iam.gserviceaccount.com type: string env_var_keys: description: |- EnvVarKeys lists the env vars the resolver injected into the probe. Values are never returned. example: - HOOP_GCP_ACCESS_TOKEN - HOOP_GCP_TOKEN_EXPIRES_AT items: type: string type: array error: description: |- Error is the human-readable failure reason when Success=false. Populated for federation-resolve failures; probe-side failures are reported via ProbeStatus + ProbeOutput. example: 'failed minting access token: permission denied' type: string probe_output: description: |- ProbeOutput is the agent's merged stdout+stderr from the smoke probe. Empty when ProbeStatus="skipped". example: |- +---+ | f0_ | +---+ | 1 | +---+ type: string probe_status: description: |- ProbeStatus reports the agent-side outcome. "success" when exit code was 0; "failed" otherwise; "skipped" when federation resolve failed and the probe was not dispatched. enum: - success - failed - skipped example: success type: string resolved_principal: description: ResolvedPrincipal is the principal the resolver impersonated. example: alice@example.com type: string success: description: |- Success is true only when federation resolved AND the agent probe returned exit code 0. example: true type: boolean superseded_env_vars: description: >- SupersededEnvVars lists the candidate connection's static env var names that the provider's output supersedes and that were therefore stripped from the probe (and would be stripped from a real session). Lets the admin UI show "these legacy credentials were ignored" so the operator can confidently remove them from the persisted connection. Example: gcp_iam supersedes GOOGLE_APPLICATION_CREDENTIALS. example: - GOOGLE_APPLICATION_CREDENTIALS items: type: string type: array token_expires_at: description: TokenExpiresAt is the would-be credential expiry. example: '2025-05-25T18:00:00Z' type: string type: object openapi.HTTPError: properties: message: example: the error description type: string type: object openapi.ConnectionFederationConfig: properties: admin_credentials_json: description: >- AdminCredentialsJSON is the plaintext admin credential blob. Its shape is provider-specific: for gcp_iam it is the admin service-account JSON; for gcp_oauth it is the OAuth client config JSON ({"client_id":"...", "client_secret":"..."}). Write-only — never returned on GET. Required on the initial POST when HookSource=builtin; optional on PUT (omitting it leaves the stored value unchanged). type: string builtin_provider: description: >- BuiltinProvider is required when HookSource=builtin. "gcp_iam" impersonates a per-user service account via an admin SA key; "gcp_oauth" mints tokens from a per-user Google OAuth refresh token (no service accounts). enum: - gcp_iam - gcp_oauth example: gcp_iam type: string connection_id: description: |- ConnectionID is the connection this federation config applies to. Populated by the server from the URL path on writes. example: 15B5A2FD-0706-4A47-B1CF-B93CCFC5B3D7 type: string created_at: description: CreatedAt / UpdatedAt are server-set audit timestamps. example: '2025-05-25T17:00:00Z' type: string extra_config: additionalProperties: {} description: |- ExtraConfig is provider-specific freeform JSON (e.g. {"project_id": "my-gcp-proj"}). The gateway does not interpret unknown keys. type: object fallback_policy: description: >- FallbackPolicy controls behavior when resolution fails. "deny" aborts the session; "static" skips federation and lets the session run on the connection's existing static credentials. enum: - deny - static example: deny type: string has_admin_credentials: description: >- HasAdminCredentials is server-set on GET responses to let the UI know whether a credential is stored without exposing its value. example: true type: boolean hook_source: description: >- HookSource selects which resolver category the gateway runs. Only the built-in resolver category ships today; the field is preserved so new sources can be added without breaking existing configurations. enum: - builtin example: builtin type: string id: description: >- ID is the federation row's UUID. Empty on POST requests; populated on GET/PUT responses. example: 15B5A2FD-0706-4A47-B1CF-B93CCFC5B3D7 type: string identity_source_attribute: description: >- IdentitySourceAttribute is a JSONPath-like accessor into the Hoop user (defaults to $.user.email). example: $.user.email type: string identity_target_template: description: >- IdentityTargetTemplate is the principal template the source attribute substitutes into (defaults to "{user.email}"). example: '{user.email}' type: string token_ttl_seconds: description: |- TokenTTLSeconds caps the lifetime of generated credentials (default 3600, max 43200). Built-in providers may clamp lower based on cloud API limits. example: 3600 type: integer updated_at: example: '2025-05-25T17:00:00Z' type: string required: - hook_source type: object openapi.FederationTestConnection: properties: agent_id: description: |- AgentID is the agent the probe will run on. Required. Must be the id of an agent currently connected to the gateway. example: 15B5A2FD-0706-4A47-B1CF-B93CCFC5B3D7 type: string command: description: |- Command is the argv the agent invokes. args[0] is the binary, args[1:] are flags. Required: keeping it caller-supplied avoids shipping connection-type-specific defaults inside the gateway that may drift from real connections. example: - bq - query - '--use_legacy_sql=false' items: type: string type: array envs: additionalProperties: type: string description: |- Envs are the candidate connection's static env vars (host, port, project id, etc.). The federation-produced env vars are merged on top; on conflict the federated value wins. type: object subtype: example: bigquery type: string test_script: description: |- TestScript is the payload fed to the spawned process on stdin (and rendered through text/template by the agent). For SQL connections this is the smoke query (e.g. "SELECT 1"). Required for the same reason as Command: the gateway does not infer it. example: SELECT 1 type: string type: description: |- Type and SubType mirror the persisted connection's type+subtype. Informational only: the gateway does not derive any behaviour from them today — the probe binary is taken from Command. They are surfaced in the response to make audit-trail correlation easier and to give future versions a structured place to plug in type-aware defaults without breaking the wire contract. example: database type: string required: - agent_id - command - test_script type: object ````