Skip to content
OneBooks Developers

Getting started

This walkthrough takes you from nothing to a working API call against a sandbox business. Total time: the coding parts take minutes; the NDA review step involves a human on our side.

  1. Create a developer account

    Sign up at the developer console with email + password and verify your email address. Developer accounts are separate from OneBooks business accounts — you don’t need (and shouldn’t reuse) a merchant login.

  2. Apply for platform access (NDA)

    The console prompts you for a short application: company name, country, phone, website, your use case and integration type. A OneBooks reviewer approves or rejects it — if rejected, you’ll see the reviewer’s note and can resubmit.

  3. Sign the developer agreement

    Once your NDA application is approved, the console shows the current Developer Agreement to sign (click-wrap). Signing activates your account and unlocks organizations, apps, webhooks and sandboxes.

  4. Create an organization and register your app

    Apps belong to an organization, not to your personal account, so teams can share them. Create an org, then create an app inside it. You choose:

    • Name — shown to businesses on the consent screen.
    • Redirect URIs — where the OAuth callback lands. https only, exact match, no wildcards, fragments or query strings (http://localhost and http://127.0.0.1 are allowed for local development).
    • Scopes — the permissions you’ll request. Start minimal; see Scopes.
    • Client type — CONFIDENTIAL (server-side, gets a secret) or PUBLIC (SPA / mobile, no secret, PKCE mandatory).

    The client secret is shown exactly once. Store it in a secrets manager now — if you lose it, rotate it from the console.

  5. Create a sandbox business

    On the console’s Sandbox page, provision a test business (org admins only). You get a one-time owner login (ownerEmail / ownerPassword — the password is never shown again). This is a real, isolated OneBooks tenant you can log into at app.getonebooks.com (opens in a new tab) and fill with test data. Details and limits: Sandbox.

  6. Authorize your app against the sandbox

    The OAuth API is included in every merchant plan, Free included, so any business can connect your app. Plans only cap how many invoices a business can create — see Scopes.

    If your app is a desktop tool, CLI or terminal with nowhere to receive a redirect, use the device flow instead of the browser redirect below.

    Generate a PKCE pair and a state value:

    Terminal window
    code_verifier=$(openssl rand -base64 48 | tr -d '=+/' | cut -c1-64)
    code_challenge=$(printf '%s' "$code_verifier" \
      | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
    state=$(openssl rand -hex 16)

    Open the authorization URL in a browser (substitute your values):

    https://app.getonebooks.com/oauth/authorize
      ?response_type=code
      &client_id=YOUR_CLIENT_ID
      &redirect_uri=https%3A%2F%2Fyourapp.example.com%2Fcallback
      &scope=accounts%3Aread
      &state=STATE
      &code_challenge=CODE_CHALLENGE
      &code_challenge_method=S256

    Sign in with the sandbox owner credentials from step 5 and approve. The browser is redirected to your redirect_uri with ?code=...&state=.... Check that state matches what you sent, then exchange the code (it’s single-use and expires in 10 minutes):

    Terminal window
    curl -s https://api.getonebooks.com/oauth/token \
      -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
      --data-urlencode "grant_type=authorization_code" \
      --data-urlencode "code=AUTH_CODE_FROM_CALLBACK" \
      --data-urlencode "redirect_uri=https://yourapp.example.com/callback" \
      --data-urlencode "code_verifier=$code_verifier"
    {
      "access_token": "…",
      "token_type": "Bearer",
      "expires_in": 3600,
      "refresh_token": "…",
      "scope": "accounts:read"
    }

  7. Make your first API call

    Terminal window
    curl -s https://api.getonebooks.com/accounts \
      -H "Authorization: Bearer $ACCESS_TOKEN"

    That returns the sandbox business’s chart of accounts. The token is bound to the business that consented — no business ID, no tenant header, ever.

Where next

Section titled “Where next”

This walkthrough covers the headless REST path. Building something a merchant opens inside OneBooks — an app page, a dialog on an invoice? Skip ahead to the embedded app quickstart, which replaces step 6 above with a session-token + token-exchange flow.

  • Platform concepts — the vocabulary the rest of these docs assume: installations, scopes, events, extensions, app data.
  • Authentication — refresh-token rotation, revocation, and the traps worth knowing before production.
  • Integration patterns — how to model POS, e-commerce and ERP data in OneBooks.
  • Go live — the review process that unlocks real businesses.
Privacy (opens in a new tab)Cookies (opens in a new tab)