Upsert an auth link draft
/auth-link-draftsCreates 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-Key
stringRequired 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. Requests rolled back before external provider attempts do not consume the key. Group mutations retain terminal failed responses after provider attempts together with received provider truth; their operation contract defines these replayable outcomes.
minLength: 1
maxLength: 255
- If-Match
string Required for a full replacement when the request identifies an existing resource. Send that resource's quoted strong etag from its last GET. A missing condition on a replacement returns 428 PRECONDITION_REQUIRED; a stale condition returns 412 PRECONDITION_FAILED. Omit this header when creating a new resource without an id. Wildcards are accepted only where the operation explicitly permits them.
minLength: 1
Request body
Returns
200
Draft auth link replaced; committed responses replay for 24 hours.
Fields
AuthLinkResponse headers
- ETag
string Opaque strong entity tag of the returned resource version. Send it back in `If-Match` on the next mutation of the same resource.
201
Draft auth link created
Fields
AuthLinkResponse headers
- ETag
string 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_REQUESTInvalid request payload
Check the request fields and any validation details, then correct the payload.
403 FORBIDDENForbidden - insufficient permissions
Check the linked account and its permissions for the device or resource.
404The supplied draft ID does not exist.
Verify the target identifier and that its endpoint or plugin route still exists.
409 CONFLICTThe Idempotency-Key request is still in flight
Check the device’s current mode or state. Retry only after the conflict is resolved.
412The draft changed since the supplied etag.
Inspect the returned code and family and follow the error handling guide.
422 UNPROCESSABLE_ENTITYThe Idempotency-Key was already used with a different payload
Correct the rejected value using the constraints in the error details or request schema.
428If-Match is required for replacement.
Inspect the returned code and family and follow the error handling guide.