Skip to main content

API reference

API authentication

How Personal Access Tokens (jbb_*) work, scope selection, IP allowlists, rotation, and the OAuth roadmap.

Last updated

The Jobby.dev API authenticates with Personal Access Tokens — bearer strings prefixed jbb_ the user mints once and pastes into their integration. No OAuth dance for v1; OAuth lands as a roadmap item once the v1 surface stabilizes.

Minting a token

Head to /account/api-tokens. Click New token, pick the scopes the integration needs, give it a label so you remember what it's for, and copy the full string. It's shown once. If you lose it, revoke it and mint a new one.

Token shape

Tokens are jbb_ + 32 base32-ish characters. The full string is the secret; we only store a SHA-256 hash on our side. We can revoke a token but cannot recover it.

Sending the token

Authorization: Bearer jbb_...

Standard RFC 6750 bearer-token shape. Don't put it in URL query strings — those land in server logs and CDN caches.

Scopes

Scopes are the permission strings the token carries. Pick the narrowest set the integration needs.

  • profile:read, profile:write
  • queue:read, queue:write
  • matches:read, matches:write
  • billing:read, billing:write
  • events:read, events:write (recruiter)
  • jobs:read, jobs:write (recruiter)
  • candidates:read, candidates:write (recruiter)
  • webhooks:read, webhooks:write
  • settings:read, settings:write

Conspicuously absent: matches:accept. Match acceptance is session-only by design — see the humans-only rule.

IP allowlists (roadmap)

Per-token IP allowlists are on the API token UX upgrade roadmap — see the open feature in specs/features.md. Today, tokens have no IP scoping. If your integration runs from a fixed egress, you can add one yourself by validating the source IP in your wrapping code.

Last-used timestamps (roadmap)

Same roadmap entry. Today, the dashboard shows token labels but not last-used time. Useful when auditing "is this token actually still in use?" — coming soon.

Rotation

To rotate: mint a new token with the same scopes, deploy it to your integration, then revoke the old one in the dashboard. Revocation is immediate; the old token returns 401 within ~5 seconds (Upstash cache window).

OAuth roadmap

OAuth 2.0 with PKCE is planned for the post-v1 surface — once the SDKs are GA and we have a few external integrators in production on PATs. Goal: enable third-party apps to drive Jobby.dev on a user's behalf without that user pasting a token. PATs will coexist forever for personal scripts and per-deployment tokens.

Related reading