Exchange a preview code for a pin

POST

/v1/mobile/preview/pair

Code sample: curl

# The Grona SDK makes this call when a tester opens a preview link. Your code does not.
curl https://api.grona.ai/v1/mobile/preview/pair \
  -H 'Content-Type: application/json' \
  -d '{"code": "K7Q2-M9XP-4RTW", "install_id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716", "workspace": "acme-market"}'

• Production

Called by the Grona SDK, not by your code, when a tester opens a preview link on a device.

The pairing code is a bearer secret: whoever opens the link gets a pin bound to their own install. Codes are single use, expire within minutes, and are rate limited per install id and per IP address.

A 200 body is the pin itself: a compact JWS (ASCII, at most 4 KB) signed with a config key, with the protected header exactly {"alg":"ES256","kid":"...","typ":"grona-pin+jwt"} and the claims ins, wks, cmp, var, iat and exp (at most 24 hours after iat). Any other status leaves the device’s pins unchanged.

Request Body^required

Media typeapplication/json

object

code

required

The pairing code from the preview link.

string

/^[A-Za-z0-9-]{8,64}$/

install_id

required

The SDK install id. The SDK never sends it while consent is denied.

string

workspace

required

string

/^[A-Za-z0-9._:-]{1,128}$/

Example

{
  "code": "K7Q2-M9XP-4RTW",
  "install_id": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
  "workspace": "acme-market"
}

Responses

200

The pin.

Media typeapplication/jose

Compact JWS with typ grona-pin+jwt.

string

<= 4096 characters

4XX

Unknown, used, expired or rate-limited code. The device’s pins are unchanged.

5XX

The device’s pins are unchanged.