Update an auth link draft

POST /{namespace}/{principalType}/{principalId}/auth-links/{authLinkId}/update-draft

Updates a DRAFT auth link. Omitted fields are unchanged. The link must still be a DRAFT and the If-Match etag must match its current version; the wildcard If-Match: * is not accepted. Requires the plugin-establish-link permission, evaluated with the variant and regionalization as operation context.

Required scope

Any authenticated access token

Path parameters

namespacestringRequired: The namespace of the principal
principalTypestringRequired: The type of principal
principalIdstringRequired: The ID of the principal
authLinkIdstringRequired: The ID of the auth link

Header parameters

If-MatchstringRequired

The quoted strong entity tag of the resource the client last read (its `etag` field or `ETag` response header). The mutation is applied only when it still matches: a stale value returns 412 PRECONDITION_FAILED and a missing header returns 428 PRECONDITION_REQUIRED. `*` matches any current version of an existing group (RFC 9110), for a deliberate last-writer-wins change.

minLength: 1

Request body

Fields

regionalizationIdstring

The plugin regionalization the link targets.

pattern: "^[a-z0-9][a-z0-9-]{0,62}$"

maxLength: 63

providerConfigurationAuthLinkProviderConfiguration

Provider-specific, non-secret configuration of an auth link.

oauthClientExistingOAuthClient | NewOAuthClient

The customer OAuth client, either an existing secret or new client credentials.

Returns

200

Draft auth link updated

Fields

idstring

The unique identifier for the auth link

pattern: "^port1/[^/]+/[^/]+/auth-links/[^/]+$"

ownerIdstring

The owner ID of the auth link

associatedPrincipalIdstring

The ID of the associated principal that the auth link is established against

associatedSecretsarray<AuthLinkSecret>

List of associated secrets that are relevant to the auth link

associatedPluginIdstring

The ID of the associated plugin

ownerPrincipal

statusstring

Lifecycle state of an auth link. A DRAFT is incomplete and not yet usable by endpoints.

Allowed values: DRAFT, CONNECTED.

authorizationVariantIdstring

The plugin authorization variant the link uses

regionalizationIdstring

The plugin regionalization the link targets

providerConfigurationAuthLinkProviderConfiguration

Provider-specific, non-secret configuration of an auth link.

etagstring

The quoted strong entity tag of the auth link, for If-Match

readOnly: true

readinessAuthLinkReadiness

Whether an auth link has everything its authorization variant requires.

readOnly: true

Response headers

ETagstring: Opaque strong entity tag of the returned resource version. Send it back in `If-Match` on the next mutation of the same resource.

Errors

403 FORBIDDEN

Forbidden - insufficient permissions

Check the linked account and its permissions for the device or resource.

404 NOT_FOUND

Auth link not found

Verify the target identifier and that its endpoint or plugin route still exists.

409 CONFLICT

The auth link is not a DRAFT

Check the device’s current mode or state. Retry only after the conflict is resolved.

412 PRECONDITION_FAILED

The If-Match etag does not match the current auth link version; re-read the link and retry

Inspect the returned code and family and follow the error handling guide.

428 PRECONDITION_REQUIRED

The If-Match header is missing, or is the wildcard *; send the etag of the draft you last read

Inspect the returned code and family and follow the error handling guide.