Make a secret to sign the context of your embeds

Makes a secret to sign the context of your embeds with, and returns it in secret: keep it now, it is shown once and cannot be read again. Keep it on your server only: whoever holds it can write contexts your compositions accept. Call this again to make a new secret; the one it replaces is still accepted for a day, so that your server can switch without an entry being refused (making another within that day ends the overlap with the first).

What signing is for. <widgetic composition-id="..." context='{"customerId":"c_42"}'> hands attribution to a widget, which sends it with every entry it saves. The page is yours but the browser is the visitor’s: anybody can change that attribute and file an entry under another customer’s id. When your server signs the context, the gateway refuses an entry whose context was changed, and the entries you keep hold attribution your server wrote.

How to sign (on your server, for each page you render):

1. Take the context to give the widget. It may hold text and whole numbers only (within ±2^53, written without a fraction or an exponent).
2. Choose when the signature stops being good: widgetic_exp, in seconds since 1970 (UTC), no more than seven days from now. A minute of difference between clocks is forgiven.
3. Write the text to sign, with no spaces except those inside values: widgetic-context.v1.<compositionId>.<widgetic_exp>.<json>. <compositionId> is the id of the composition in lower case. <json> is the context as JSON with the keys in character-code order (so Z comes before a, and 10 before 9), no spaces, strings escaped as JSON escapes them, and the two keys of the signature left out.
4. Sign that text: HMAC-SHA256 with the 32 bytes the secret stands for (the base64 text after ctxsec_), and write the result as base64url without padding.
5. Give the widget the context with two keys added: widgetic_exp and widgetic_sig (the signature). The whole attribute, the two keys included, stays within the limits of any context: at most 20 keys, 2048 bytes of JSON, strings up to 500 characters. The two keys take two of the 20 keys and 87 bytes of the 2048.

A test vector, to check your code against before you rely on it. Secret ctxsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8= (the bytes 0 to 31), composition 7c9e6679-7425-40de-944b-e07fc1f90ae7, widgetic_exp 1792000000 and context {"customerId":"c_42","plan":"pro","seats":3} sign the text widgetic-context.v1.7c9e6679-7425-40de-944b-e07fc1f90ae7.1792000000.{"customerId":"c_42","plan":"pro","seats":3} and give the signature j6g7151F54tl9C8oEY9levaYSppHME4fAPZ7WPwL8C8. (The secret is the example’s, not a real one.)

What the gateway does with an entry. When you have a secret, an entry whose context carries a signature is checked: a signature that does not match is refused with 403 CONTEXT_SIGNATURE_INVALID, and one that is past widgetic_exp with 403 CONTEXT_SIGNATURE_EXPIRED. When you also require signatures (updatePartnerEntryContextSigning) an entry whose context carries none is refused with 403 CONTEXT_SIGNATURE_REQUIRED. The two keys are taken out before the entry is stored or announced: your entries and your entry.created events hold the context you wrote. A change you make reaches every part of the gateway within a minute.

What it does not do. A signed context that has been seen (a page’s source is public) can be sent again by anyone until widgetic_exp; when you must not accept the same context twice, put a value that is new for each page view in it (a submissionId you made up) and keep the ones you have seen. The signature covers the entries that reach Widgetic’s gateway: a row that gets into a table another way (your own code writing straight into a database you brought, or the record calls of the composition’s owner) does not pass through it, and carries no context.

Retry this call with the same Idempotency-Key if its answer was lost: the answer, secret included, is then given again, and no second secret is made. This needs an API key with full access. The caller must be the person who administers the partner, or a Widgetic administrator.

POST /partners/{partnerId}/entry-context-signing/secret

TypeScript

TypeScript SDK

import { randomUUID } from 'node:crypto'; import { Configuration, PartnersApi } from '@widgetic/api-sdk-ts'; const partnersApi = new PartnersApi(new Configuration({ apiKey: 'YOUR_API_KEY' })); const { data: made } = await partnersApi.rotatePartnerEntryContextSecret({ partnerId, idempotencyKey: randomUUID() }); // Shown once: keep it on your server now. console.log(made.secret);

200

{
  "success": true,
  "data": {
    "signing": null,
    "secret": "Example secret"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string · required

Required: a call without it is refused with 400. A key of your own that names this one request; a UUID is ideal. It is 8 to 50 characters of letters, digits, - and _. Send the same key again when you retry (after a timeout, a dropped connection or a 5xx) and the call is carried out once: the retry gets the first answer back, marked X-Idempotency-Cached: true. The same key with a different body is refused with 422, and a retry that arrives while the first call is still running with 409 (see Retry-After).

Required string length: 8 - 50

Pattern: ^[a-zA-Z0-9_-]{8,50}$

Example:

"9b2d6f0a-3c41-4e5a-8d77-1f2e3a4b5c6d"

Path Parameters

partnerId · string<uuid> · required

The partner whose secret to make

Response

200

application/json

The new secret, and how your signing stands now

success · boolean · required

Always true on a success.

Example:

true

data · object · required

A new signing secret, and how your signing stands now.

Show child attributes

Example:

{
  "signing": null,
  "secret": "Example secret"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes