docs: add guide for signing Admin API requests #3807
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
brad-dow
requested review from
BlairCurrey,
hajjimo,
melissahenderson and
mkurapov
✅ Deploy Preview for brilliant-pasca-3e80ec ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
github-actions
bot
added
the
pkg: documentation
🚀 Performance Test ResultsTest Configuration:
Test Metrics:
📜 Logs |
melissahenderson
approved these changes
Jan 26, 2026
BlairCurrey
reviewed
Jan 28, 2026
Contributor
BlairCurrey
left a comment
BlairCurrey
left a comment
There was a problem hiding this comment.
I dont see any technical accuracy problems. Just the one tenant-id casing issue and a suggestion for the js example which is really more for Max.
|
|
||
| Each request is HMAC‑signed with SHA‑256 using the tenant’s or operator’s API secret. This signature ensures that Rafiki can verify where the request originated and confirm that the payload data matches what was originally signed. | ||
|
|
||
| All signed requests include two headers: the `signature` header and the `tenant-Id` header. |
Contributor
There was a problem hiding this comment.
Suggested change
| All signed requests include two headers: the `signature` header and the `tenant-Id` header. | |
| All signed requests include two headers: the `signature` header and the `tenant-id` header. |
Comment on lines
+87
to
+103
| const timestamp = Date.now() | ||
| const version = process.env.ADMIN_API_SIGNATURE_VERSION | ||
|
|
||
| const { query, variables, operationName } = request | ||
| const formattedRequest = { | ||
| variables, | ||
| operationName, | ||
| query: print(query) | ||
| } | ||
|
|
||
| const payload = `${timestamp}.${canonicalize(formattedRequest)}` | ||
| const hmac = createHmac('sha256', process.env.ADMIN_API_SECRET) | ||
| hmac.update(payload) | ||
| const digest = hmac.digest('hex') | ||
|
|
||
| headers['signature'] = `t=${timestamp}, v${version}=${digest}` | ||
| headers['tenant-id'] = process.env.OPERATOR_TENANT_ID |
Contributor
There was a problem hiding this comment.
@mkurapov thoughts on making what the request looks like more explicit? I have some familiarity with our implementation (which this comes from) but I still had to stop and think about what formattedRequest really is, other than "some GQL request in whatever form we need here". What I find unclear currently:
requestis not defined anywhere. We can kinda reason about what we destructure off of it but we dont know exactly. Is query a string, object, some special gql class instance? (it's the latter)printis not defined anywhere
In addition to making it more explicit, it might be useful to use less libraries. This js implementation is an example that should illustrate the concept in general. Someone might need to do this in go, rust etc. I figure the less magic happening from third party libraries the better. And for that matter, someone in js might not be using the same gql libraries.
What I would probably suggest is the more explicit one with less 3rd party libraries:
import { createHmac } from "crypto";
import { canonicalize } from "json-canonicalize";
const timestamp = Date.now();
const version = process.env.ADMIN_API_SIGNATURE_VERSION;
const requestBody = {
query: `
query GetAsset($id: String!) {
asset(id: $id) {
id
code
scale
}
}
`,
variables: { id: "asset-id-here" },
operationName: "GetAsset",
};
// Canonicalize ensures both client and server produce identical JSON strings
// by sorting object keys deterministically and normalizing whitespace.
const payload = `${timestamp}.${canonicalize(requestBody)}`;
const hmac = createHmac('sha256', process.env.ADMIN_API_SECRET)
hmac.update(payload)
const digest = hmac.digest('hex')
headers['signature'] = `t=${timestamp}, v${version}=${digest}`
headers['tenant-id'] = process.env.OPERATOR_TENANT_IDOr the more explicit version of what we already have with print and the gql tagged function:
import { createHmac } from 'crypto'
import { canonicalize } from 'json-canonicalize'
import { gql } from '@apollo/client'
import { print } from 'graphql/language/printer'
const timestamp = Date.now()
const version = process.env.ADMIN_API_SIGNATURE_VERSION
const GET_ASSET = gql`
query GetAsset($id: String!) {
asset(id: $id) {
id
code
scale
}
}
`
const requestBody = {
query: print(GET_ASSET), // converts `DocumentNode` to string
variables: { id: 'asset-id-here' },
operationName: 'GetAsset'
}
// Canonicalize ensures both client and server produce identical JSON strings
// by sorting object keys deterministically and normalizing whitespace.
const payload = `${timestamp}.${canonicalize(requestBody)}`
const hmac = createHmac('sha256', process.env.ADMIN_API_SECRET)
hmac.update(payload)
const digest = hmac.digest('hex')
headers['signature'] = `t=${timestamp}, v${version}=${digest}`
headers['tenant-id'] = process.env.OPERATOR_TENANT_ID
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description of changes
Fixes #3690
This update adds a new "Signing Admin API requests" guide that explains how a client can generate and include HMAC SHA-256 signatures when calling the Backend Admin API.
The guide includes the following:
Required
Conditional