Skip to content
Macro DeckMacro Deck Docs

Redeem an approved pairing request for a plugin credential

POST
/api/plugins/pairing/{requestId}/redemption
curl --request POST \
  --url https://example.com/api/plugins/pairing/example/redemption \
  --header 'Content-Type: application/json' \
  --data '{ "codeVerifier": "example" }'

Unknown, expired, unapproved, already-redeemed and wrong-verifier request/verifier combinations all answer 401 indistinguishably, deliberately - the same oracle argument as registration authentication.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
requestId
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Mirrors MacroDeck.Plugin.Protocol.Handshake.PluginPairingRedemptionRequest.

object
codeVerifier
required
string
Examplegenerated
{
  "codeVerifier": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

The pairing request was redeemed. The secret is shown exactly once.

Media typeapplication/json

Mirrors MacroDeck.Plugin.Protocol.Handshake.PluginRegistrationResponse.

object
pluginId
required
string
pluginSecret
required

Shown exactly once. The host stores only its hash.

string
Examplegenerated
{
  "pluginId": "example",
  "pluginSecret": "example"
}

400

Section titled “400”

The request body does not match the expected shape.

Media typeapplication/json

Mirrors MacroDeck.Plugin.Protocol.Errors.ProtocolError.

object
code
required

One of the codes v1 speaks. Drift anchor - see x-macrodeck-error-codes above.

string
Allowed values: PROTOCOL_VERSION_UNSUPPORTED UNKNOWN_MESSAGE_TYPE MALFORMED_ENVELOPE INVALID_PAYLOAD UNAUTHENTICATED PLUGIN_ALREADY_REGISTERED SESSION_EXPIRED SESSION_NOT_RESUMABLE SESSION_REPLACED SESSION_NOT_FOUND CAPABILITY_UNSUPPORTED CAPABILITY_UNAVAILABLE PAYLOAD_TOO_LARGE ASSET_TOO_LARGE QUEUE_OVERFLOW RATE_LIMITED TIMEOUT CANCELLED CORRELATION_UNKNOWN DUPLICATE_IDEMPOTENCY_KEY INTERNAL_ERROR
message
required

Default English text keyed by code (MacroDeck.Plugin.Protocol.Errors.ProtocolErrorMessages). The UI localises from the code, not this string.

string
details
object
key
additional properties
string
retryable
required
boolean
Example
{
  "code": "PROTOCOL_VERSION_UNSUPPORTED"
}

401

Section titled “401”

Authentication failed. An unknown id and a wrong secret are indistinguishable in the response, the same oracle argument as device login.

Media typeapplication/json

Mirrors MacroDeck.Plugin.Protocol.Errors.ProtocolError.

object
code
required

One of the codes v1 speaks. Drift anchor - see x-macrodeck-error-codes above.

string
Allowed values: PROTOCOL_VERSION_UNSUPPORTED UNKNOWN_MESSAGE_TYPE MALFORMED_ENVELOPE INVALID_PAYLOAD UNAUTHENTICATED PLUGIN_ALREADY_REGISTERED SESSION_EXPIRED SESSION_NOT_RESUMABLE SESSION_REPLACED SESSION_NOT_FOUND CAPABILITY_UNSUPPORTED CAPABILITY_UNAVAILABLE PAYLOAD_TOO_LARGE ASSET_TOO_LARGE QUEUE_OVERFLOW RATE_LIMITED TIMEOUT CANCELLED CORRELATION_UNKNOWN DUPLICATE_IDEMPOTENCY_KEY INTERNAL_ERROR
message
required

Default English text keyed by code (MacroDeck.Plugin.Protocol.Errors.ProtocolErrorMessages). The UI localises from the code, not this string.

string
details
object
key
additional properties
string
retryable
required
boolean
Example
{
  "code": "PROTOCOL_VERSION_UNSUPPORTED"
}

403

Section titled “403”

The caller did not arrive on a loopback remote address. Plugin endpoints are served on both the public and private listeners, but only local processes may reach them. On the pairing endpoints, on POST /api/plugins/registration, and on POST /api/plugins/sessions for a plugin holding a development credential, this status also means Developer Mode is switched off in the desktop app - such a refusal carries “reason”: “developer_mode_disabled” in the error’s details, and GET /api/plugins/protocol reports the switch ahead of time.

Media typeapplication/json

Mirrors MacroDeck.Plugin.Protocol.Errors.ProtocolError.

object
code
required

One of the codes v1 speaks. Drift anchor - see x-macrodeck-error-codes above.

string
Allowed values: PROTOCOL_VERSION_UNSUPPORTED UNKNOWN_MESSAGE_TYPE MALFORMED_ENVELOPE INVALID_PAYLOAD UNAUTHENTICATED PLUGIN_ALREADY_REGISTERED SESSION_EXPIRED SESSION_NOT_RESUMABLE SESSION_REPLACED SESSION_NOT_FOUND CAPABILITY_UNSUPPORTED CAPABILITY_UNAVAILABLE PAYLOAD_TOO_LARGE ASSET_TOO_LARGE QUEUE_OVERFLOW RATE_LIMITED TIMEOUT CANCELLED CORRELATION_UNKNOWN DUPLICATE_IDEMPOTENCY_KEY INTERNAL_ERROR
message
required

Default English text keyed by code (MacroDeck.Plugin.Protocol.Errors.ProtocolErrorMessages). The UI localises from the code, not this string.

string
details
object
key
additional properties
string
retryable
required
boolean
Example
{
  "code": "PROTOCOL_VERSION_UNSUPPORTED"
}

429

Section titled “429”

Too many requests.

Media typeapplication/json

Mirrors MacroDeck.Plugin.Protocol.Errors.ProtocolError.

object
code
required

One of the codes v1 speaks. Drift anchor - see x-macrodeck-error-codes above.

string
Allowed values: PROTOCOL_VERSION_UNSUPPORTED UNKNOWN_MESSAGE_TYPE MALFORMED_ENVELOPE INVALID_PAYLOAD UNAUTHENTICATED PLUGIN_ALREADY_REGISTERED SESSION_EXPIRED SESSION_NOT_RESUMABLE SESSION_REPLACED SESSION_NOT_FOUND CAPABILITY_UNSUPPORTED CAPABILITY_UNAVAILABLE PAYLOAD_TOO_LARGE ASSET_TOO_LARGE QUEUE_OVERFLOW RATE_LIMITED TIMEOUT CANCELLED CORRELATION_UNKNOWN DUPLICATE_IDEMPOTENCY_KEY INTERNAL_ERROR
message
required

Default English text keyed by code (MacroDeck.Plugin.Protocol.Errors.ProtocolErrorMessages). The UI localises from the code, not this string.

string
details
object
key
additional properties
string
retryable
required
boolean
Example
{
  "code": "PROTOCOL_VERSION_UNSUPPORTED"
}

Headers

Section titled “Headers”
Retry-After
required
integer format: int32