Skip to main content

Lambda response schema

Request​

The broker accepts exactly one thing: an empty payload or the literal JSON value null. Anything else — including {} — is rejected. See Why empty payloads are enforced.

When invoking with the AWS CLI, use --payload 'null':

aws lambda invoke \
  --function-name github-token-broker \
  --payload 'null' \
  --cli-binary-format raw-in-base64-out \
  /tmp/out.json

Success response​

On success the broker returns a JSON object:

{
  "token": "ghs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2026-04-23T17:12:00Z",
  "repositories": ["your-org/your-repo"],
  "permissions": {"contents": "read"}
}
FieldTypeDescription
tokenstringGitHub installation token in the ghs_… format. Use it as a Bearer token against the GitHub API.
expires_atRFC 3339 timestampToken expiration, returned verbatim from the GitHub API. Do not assume a hardcoded lifetime.
repositoriesarray of stringsSingle-element array: ["<owner>/<repo>"]. Matches the GITHUB_TOKEN_BROKER_REPOSITORY_OWNER and _NAME configuration.
permissionsobject of stringsThe permission set requested at mint time. Mirrors GITHUB_TOKEN_BROKER_PERMISSIONS.

Token lifetime​

GitHub returns the authoritative expires_at. The default lifetime is approximately one hour, but the GitHub API is the source of truth — callers should read expires_at rather than hardcoding a duration.

Logging policy​

The broker never logs the token. At info level, every successful mint emits:

level=info msg="minted GitHub installation token" repositories=[owner/repo] expires_at=<RFC3339>

That line is your signal that a mint succeeded. If it is absent, the mint failed. See errors for failure modes.

Error response​

On failure the Lambda returns an error (not a success response with an error body). See errors for the error messages the broker surfaces.

See also​