Disconnect an auth link and keep its app configuration

POST /{namespace}/{principalType}/{principalId}/auth-links/{authLinkId}/disconnect

Signs a customer-owned OAuth auth link out of its provider while keeping the OAuth app the customer registered. The provider tokens are deleted, the link's routes and the endpoints that exist only for it are removed, and the link returns to DRAFT with its OAuth client ID, client secret and provider configuration intact. The customer can authorize it again without entering them. Port OS does not call a provider revocation endpoint: the tokens are dropped from Port OS only.

The link must be CONNECTED, must use a customer-owned OAuth authorization variant and must hold its own OAUTH_CLIENT secret. A link that uses the Port OS app (portos-oauth), or any other variant, has no saved app configuration to keep: it is refused with AUTH_LINK_NOT_DISCONNECTABLE and is removed with deleteAuthLink. A link that is already a DRAFT is a 409 CONFLICT. The If-Match etag must match the link's current version; the wildcard If-Match: * is not accepted. The response carries the new ETag.

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

Returns

200

The auth link is disconnected and is a DRAFT again, with its app configuration kept

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 AUTH_LINK_NOT_DISCONNECTABLE

The auth link is already a DRAFT (CONFLICT), or it keeps no app configuration of the customer (AUTH_LINK_NOT_DISCONNECTABLE); delete it instead

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 link you last read

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