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.

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.
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.
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.

If OneBooks later publishes a new agreement version, the console locks the same surfaces until you sign it. Your apps keep running — only the console is gated.
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.
Create a sandbox business

From your org’s Sandbox tab, provision a test business. 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 and fill with test data. Details and limits: Sandbox.

Authorize your app against the sandbox

Generate a PKCE pair and a state value:

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):

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"
}

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

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.