Create an auth link draft

POST /auth-link-drafts

Creates a DRAFT auth link for a plugin authorization variant and regionalization. A draft holds the customer-owned OAuth client and provider configuration while the customer completes setup; it is not usable by endpoints until the provider connection is established. Requires the plugin-establish-link permission, evaluated with the variant and regionalization as operation context. The same Idempotency-Key and payload replays the committed response.

Required scope

Any authenticated access token

Header parameters

Idempotency-KeystringRequired

Client-chosen key that makes a non-idempotent request retry-safe, following draft-ietf-httpapi-idempotency-key-header. A committed response is stored for 24 hours and replayed for the same principal, operation, key and payload. Missing key returns 400 IDEMPOTENCY_KEY_REQUIRED, a key longer than 255 characters returns 400 IDEMPOTENCY_KEY_INVALID, the same key with a different payload returns 422, and the same key while the first request is still in flight returns 409. Failed (rolled-back) requests do not consume the key.

minLength: 1

maxLength: 255

Request body

Fields

pluginIdstringRequired

The plugin the link is for.

authorizationVariantIdstringRequired

The plugin authorization variant the link uses.

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

maxLength: 63

regionalizationIdstringRequired

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

201

Draft auth link created

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

400 BAD_REQUEST

Invalid request payload

Check the request fields and any validation details, then correct the payload.

403 FORBIDDEN

Forbidden - insufficient permissions

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

409 CONFLICT

The Idempotency-Key request is still in flight

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

422 UNPROCESSABLE_ENTITY

The Idempotency-Key was already used with a different payload

Correct the rejected value using the constraints in the error details or request schema.