Skip to main content
PUT
/
connections
/
{nameOrID}
/
federation
Upsert Federation Configuration for a Connection
curl --request PUT \
  --url https://use.hoop.dev/api/connections/{nameOrID}/federation \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'
{
  "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"
}

Path Parameters

​
nameOrID
string
required

Name or UUID of the connection

Body

application/json

The request body resource

​
hook_source
enum<string>
required

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.

Available options:
builtin
Example:

"builtin"

​
admin_credentials_json
string

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).

​
builtin_provider
enum<string>

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).

Available options:
gcp_iam,
gcp_oauth
Example:

"gcp_iam"

​
connection_id
string

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"

​
created_at
string

CreatedAt / UpdatedAt are server-set audit timestamps.

Example:

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

​
extra_config
object

ExtraConfig is provider-specific freeform JSON (e.g. {"project_id": "my-gcp-proj"}). The gateway does not interpret unknown keys.

​
fallback_policy
enum<string>

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.

Available options:
deny,
static
Example:

"deny"

​
has_admin_credentials
boolean

HasAdminCredentials is server-set on GET responses to let the UI know whether a credential is stored without exposing its value.

Example:

true

​
id
string

ID is the federation row's UUID. Empty on POST requests; populated on GET/PUT responses.

Example:

"15B5A2FD-0706-4A47-B1CF-B93CCFC5B3D7"

​
identity_source_attribute
string

IdentitySourceAttribute is a JSONPath-like accessor into the Hoop user (defaults to $.user.email).

Example:

"$.user.email"

​
identity_target_template
string

IdentityTargetTemplate is the principal template the source attribute substitutes into (defaults to "{user.email}").

Example:

"{user.email}"

​
token_ttl_seconds
integer

TokenTTLSeconds caps the lifetime of generated credentials (default 3600, max 43200). Built-in providers may clamp lower based on cloud API limits.

Example:

3600

​
updated_at
string
Example:

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

Response

OK

​
hook_source
enum<string>
required

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.

Available options:
builtin
Example:

"builtin"

​
admin_credentials_json
string

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).

​
builtin_provider
enum<string>

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).

Available options:
gcp_iam,
gcp_oauth
Example:

"gcp_iam"

​
connection_id
string

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"

​
created_at
string

CreatedAt / UpdatedAt are server-set audit timestamps.

Example:

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

​
extra_config
object

ExtraConfig is provider-specific freeform JSON (e.g. {"project_id": "my-gcp-proj"}). The gateway does not interpret unknown keys.

​
fallback_policy
enum<string>

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.

Available options:
deny,
static
Example:

"deny"

​
has_admin_credentials
boolean

HasAdminCredentials is server-set on GET responses to let the UI know whether a credential is stored without exposing its value.

Example:

true

​
id
string

ID is the federation row's UUID. Empty on POST requests; populated on GET/PUT responses.

Example:

"15B5A2FD-0706-4A47-B1CF-B93CCFC5B3D7"

​
identity_source_attribute
string

IdentitySourceAttribute is a JSONPath-like accessor into the Hoop user (defaults to $.user.email).

Example:

"$.user.email"

​
identity_target_template
string

IdentityTargetTemplate is the principal template the source attribute substitutes into (defaults to "{user.email}").

Example:

"{user.email}"

​
token_ttl_seconds
integer

TokenTTLSeconds caps the lifetime of generated credentials (default 3600, max 43200). Built-in providers may clamp lower based on cloud API limits.

Example:

3600

​
updated_at
string
Example:

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