Authentication

Every request to the review API carries a Proofline token in the Authorization header. A token works in one organization, with the scopes and repositories chosen when it was created.

import { ProoflineClient } from "@proofline/sdk";

// The client sends the token in the Authorization header of every request.
const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const page = await client.listReviews({
  path: { org_id: process.env.PROOFLINE_ORGANIZATION_ID! },
});
console.log(page.items.length);

import os
from uuid import UUID
from proofline import ProoflineClient

# The client sends the token in the Authorization header of every request.
with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    page = client.list_reviews(UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]))
    print(len(page.items))

curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/reviews" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"

Tokens#

A token acts with its holder's current GitHub identity and access. It reads or requests reviews and never changes configuration, billing, seats, cloud access, integrations or other tokens. Those actions need a signed-in browser.

The console shows a token's secret once, when you create it. Revoking a token takes effect on its next request.

Scopes#

Each operation needs one scope. Give a token only the scopes its job needs.

A token can also be limited to a list of repositories. An organization token that requests or reruns reviews must name its repositories. A pull request review request and a rerun check that the holder can still write to the repository on GitHub. A review request for local changes checks that the holder can still read it, because that review is never posted to GitHub.

Errors#

Errors are RFC 9457 problem documents, and the HTTP status is authoritative.

A 404 also answers when the holder has left the organization, or when the administrator who created an organization token has lost that role.

Device sign-in#

A command-line tool signs in through your browser, so you never copy a token. The tool asks for a code, opens the approval page, and waits while you choose the organization, the scopes and the repositories.

1. The tool sends POST /auth/device/code with the scopes it wants. The response has a device_code, a user_code, a verification_uri and a verification_uri_complete.
2. The tool opens verification_uri_complete in your browser. The page shows the code, so you only check that it matches the one in your terminal.
3. You approve. The approval needs a signed-in browser session, and you can narrow the scopes and repositories first.
4. The tool polls POST /auth/device/token with the device_code and grant_type=urn:ietf:params:oauth:grant-type:device_code. It receives an access_token, a CLI device token that lasts 14 days, and an organization_id naming the organization you approved. The token works only there, so the tool puts that ID in every API path.

The code expires after 10 minutes. Poll every 5 seconds to start with. Before approval, polling returns authorization_pending; polling too fast returns slow_down and adds five seconds to the interval. An expired or used code returns expired_token. Each code issues one token, however many times it is polled.