Skip to main content
POST
/
federation
/
test
Test a Federation Configuration End-to-End
curl --request POST \
  --url https://use.hoop.dev/api/federation/test \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {
    "hook_source": "builtin",
    "admin_credentials_json": "<string>",
    "builtin_provider": "gcp_iam",
    "connection_id": "15B5A2FD-0706-4A47-B1CF-B93CCFC5B3D7",
    "created_at": "2025-05-25T17:00:00Z",
    "extra_config": {},
    "fallback_policy": "deny",
    "has_admin_credentials": true,
    "id": "15B5A2FD-0706-4A47-B1CF-B93CCFC5B3D7",
    "identity_source_attribute": "$.user.email",
    "identity_target_template": "{user.email}",
    "token_ttl_seconds": 3600,
    "updated_at": "2025-05-25T17:00:00Z"
  },
  "connection": {
    "agent_id": "15B5A2FD-0706-4A47-B1CF-B93CCFC5B3D7",
    "command": [
      "bq",
      "query",
      "--use_legacy_sql=false"
    ],
    "test_script": "SELECT 1",
    "envs": {},
    "subtype": "bigquery",
    "type": "database"
  },
  "user_email": "alice@example.com",
  "user_id": "00000000-0000-0000-0000-000000000001"
}
'
{
  "admin_principal": "hoop-admin@proj.iam.gserviceaccount.com",
  "env_var_keys": [
    "HOOP_GCP_ACCESS_TOKEN",
    "HOOP_GCP_TOKEN_EXPIRES_AT"
  ],
  "error": "failed minting access token: permission denied",
  "probe_output": "+---+\n| f0_ |\n+---+\n| 1 |\n+---+",
  "probe_status": "success",
  "resolved_principal": "alice@example.com",
  "success": true,
  "superseded_env_vars": [
    "GOOGLE_APPLICATION_CREDENTIALS"
  ],
  "token_expires_at": "2025-05-25T18:00:00Z"
}

Body

application/json

The request body resource

​
config
object
required

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
object
required

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
string
required

UserEmail is the synthetic user to resolve. Required.

Example:

"alice@example.com"

​
user_id
string

UserID is the synthetic user ID. Optional; defaults to a deterministic UUID derived from UserEmail.

Example:

"00000000-0000-0000-0000-000000000001"

Response

OK

​
admin_principal
string

AdminPrincipal is the impersonator identity (e.g. admin SA email).

Example:

"hoop-admin@proj.iam.gserviceaccount.com"

​
env_var_keys
string[]

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"
]
​
error
string

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"

​
probe_output
string

ProbeOutput is the agent's merged stdout+stderr from the smoke probe. Empty when ProbeStatus="skipped".

Example:

"+---+\n| f0_ |\n+---+\n| 1 |\n+---+"

​
probe_status
enum<string>

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.

Available options:
success,
failed,
skipped
Example:

"success"

​
resolved_principal
string

ResolvedPrincipal is the principal the resolver impersonated.

Example:

"alice@example.com"

​
success
boolean

Success is true only when federation resolved AND the agent probe returned exit code 0.

Example:

true

​
superseded_env_vars
string[]

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"]
​
token_expires_at
string

TokenExpiresAt is the would-be credential expiry.

Example:

"2025-05-25T18:00:00Z"