OAuth Apps

​

How it works

​

Part 1: Register your app

1

Open the Apps page

Go to Settings > Developer > Apps. If you haven’t created an app yet, you’ll see the empty state. Click Create App. Once you have at least one app, the button is New App in the top right.If you already have a manifest, click Create from Manifest (From Manifest once you have apps) and paste it instead. That sets up the details, permissions and extensions in one step.

If you don’t see Apps under Developer, contact your Campfire support team to have OAuth apps turned on for your workspace.

2

Fill in the app details

The Details tab describes your app to the people who will authorize it.

Field	Required	What it’s for
Name	Yes	Shown on the consent screen, the Connections page, and the activity log.
Tagline	No	One line (up to 120 characters) shown under the name on the app card and the consent screen.
Category	No	Where the app is listed on the Connections page: Accounts Payable, Accounts Receivable, Banking, CRM, Data, Payroll, or Tax. Leave it as Other to list the app under Apps.
Description	No	Up to 2,000 characters that help your colleagues recognize what the app does. Shown on the connection’s detail page.
List of allowed redirection URLs	To authorize	Where Campfire sends people back after they approve or deny access. Add up to 20 with Add new URL. People can’t authorize the app until at least one is added.
Connect URL	No	Where the Connect button on Campfire’s Connections page sends people. See Starting from Campfire.
Manage URL	No	Where the Manage in <App> button on the connection page sends people, with a signed context token. See Manage URL.
App icon	No	PNG, JPG, GIF, or WEBP, up to 1 MB. Shown on the consent screen and the Connections page.
Published	No	Off by default. See Private vs. published apps.

Redirect URLs, the Connect URL, and the Manage URL must use https. Plain http is accepted only for localhost, 127.0.0.1, and [::1], so you can develop locally. URLs can’t contain a #fragment or embedded credentials. At authorization time the redirect_uri must exactly match one of the registered URLs, except that loopback addresses (127.0.0.1, [::1]) may use any port.

3

Choose the app's permissions

Switch to the Permissions tab and check the access your app needs. These scopes are the ceiling: the most the app can ever request. People connecting the app are still limited to their own permissions in the workspace they choose.

Permissions are grouped by module (Accounting, Revenue, Reports, Cash Management, Close Management, Organization, Ember AI). Each row is a resource, and each column is an access tier:

Tier	Grants
Read	View the resource.
Draft	Propose changes that go through Campfire’s approval workflow. The app’s writes are saved as drafts for someone to approve.
Write	Create, edit, and delete the resource.
Approve	Approve proposed changes to the resource. This is separate from the other tiers and only granted on its own.

A higher tier includes the lower ones. For example, checking Write on Invoice Payments also checks Read and Draft. Only check what your integration actually uses. You can widen the scopes later, through a new version, without affecting existing connections.

You can create an app with no permissions. It can then only confirm who signed in and which workspace they chose. For “Sign in with Campfire”, also add the openid, email, and profile scopes; see OpenID Connect.

4

Save and copy your credentials

Click Create App. Campfire shows the app’s credentials:

Credential	Use
Client ID	Public identifier for your app. Safe to include in URLs.
Client Secret	Proves your server is the app. Keep it in a secret store and never ship it to a browser or mobile app.
Auth URL	A ready-made authorize URL for your first redirect URL. Add state, scope, and PKCE parameters as shown below.
Access Token URL / Refresh Token URL	https://api.meetcampfire.com/ca/oauth/token. The same endpoint handles both grants.

The client secret is shown only once. Copy it before you click Done. If you lose it, rotate it to get a new one (see Rotating the client secret).

Your app now appears on the Apps page with its scope count and its production version. Click Manage to open it.

​

Part 2: Implement the authorization flow

​

Step 1: Send the person to Campfire

https://api.meetcampfire.com/ca/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyour-app.com%2Foauth%2Fcallback
  &response_type=code
  &scope=invoices%3Aread%20invoice_payments%3Awrite%20vendors%3Aread
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

import base64, hashlib, secrets

code_verifier = secrets.token_urlsafe(48)  # 43-128 characters
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode()).digest()
).rstrip(b"=").decode()
state = secrets.token_urlsafe(24)

import crypto from "node:crypto";

const codeVerifier = crypto.randomBytes(48).toString("base64url"); // 43-128 characters
const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");
const state = crypto.randomBytes(24).toString("base64url");

​

Step 2: The person approves access

• Workspace. For a private app, the workspace is fixed to the one that created the app. For a published and approved app, the person picks one of the workspaces they belong to.
• Authorize redirects to your redirect_uri with code and state:
  https://your-app.com/oauth/callback?code=I9feIWu7cmfy...&state=RANDOM_STATE
  
• Cancel redirects to your redirect_uri with an error:
  https://your-app.com/oauth/callback?error=access_denied&error_description=The+user+declined+to+authorize+the+app.&state=RANDOM_STATE
  

​

Step 3: Exchange the code for tokens

curl -X POST https://api.meetcampfire.com/ca/oauth/token \
  -u "$CAMPFIRE_CLIENT_ID:$CAMPFIRE_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://your-app.com/oauth/callback" \
  -d code_verifier="$CODE_VERIFIER"

{
  "access_token": "cfa_YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoice_payments:write invoices:read vendors:read",
  "refresh_token": "cfr_YOUR_REFRESH_TOKEN"
}

​

Step 4: Call the API

curl https://api.meetcampfire.com/coa/api/v1/invoice/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl https://api.meetcampfire.com/users/api/get-user-permissions \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": 45460,
  "name": "Jordan Lee",
  "email": "jordan@example.com",
  "approval_required": false,
  "can_edit": false,
  "tenant": {
    "id": 53,
    "name": "Example Co",
    "type": "PRODUCTION",
    "logo_url": null
  },
  "app": {
    "client_id": "fg2-mFFHRkQmqiVvXMXdbEBfDfZp4Evh",
    "scopes": ["invoice_payments:write", "invoices:read", "vendors:read"]
  },
  "permissions": {
    "chart_of_accounts.accountinginvoice": "read",
    "chart_of_accounts.accountingbill": "none"
  }
}

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="api", error="insufficient_scope", scope="bills:read"

{"detail": "You do not have permission to perform this action."}

​

Step 5: Refresh the access token

curl -X POST https://api.meetcampfire.com/ca/oauth/token \
  -u "$CAMPFIRE_CLIENT_ID:$CAMPFIRE_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

{"error": "invalid_grant", "error_description": "Refresh token was already used; re-authorize the app."}

​

Starting the flow from Campfire

@app.get("/campfire/connect")
def connect():
    verifier, challenge = pkce_pair()
    state = secrets.token_urlsafe(24)
    session["oauth"] = {"state": state, "verifier": verifier}
    return redirect(AUTHORIZE_URL + "?" + urlencode({
        "client_id": CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "response_type": "code",
        "state": state,
        "code_challenge": challenge,
        "code_challenge_method": "S256",
    }))

​

A complete example

import base64, hashlib, os, secrets
from urllib.parse import urlencode

import requests
from flask import Flask, redirect, request, session, url_for

CAMPFIRE_API = "https://api.meetcampfire.com"
CLIENT_ID = os.environ["CAMPFIRE_CLIENT_ID"]
CLIENT_SECRET = os.environ["CAMPFIRE_CLIENT_SECRET"]
REDIRECT_URI = os.environ.get("REDIRECT_URI", "http://localhost:3999/callback")

app = Flask(__name__)
app.secret_key = os.environ["FLASK_SECRET"]


def pkce_pair():
    verifier = secrets.token_urlsafe(48)
    challenge = base64.urlsafe_b64encode(
        hashlib.sha256(verifier.encode()).digest()
    ).rstrip(b"=").decode()
    return verifier, challenge


@app.get("/connect")
def connect():
    verifier, challenge = pkce_pair()
    state = secrets.token_urlsafe(24)
    session["oauth"] = {"state": state, "verifier": verifier}
    query = {
        "client_id": CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "response_type": "code",
        "scope": "invoices:read invoice_payments:write vendors:read",
        "state": state,
        "code_challenge": challenge,
        "code_challenge_method": "S256",
    }
    return redirect(f"{CAMPFIRE_API}/ca/oauth/authorize?{urlencode(query)}")


@app.get("/callback")
def callback():
    pending = session.pop("oauth", None)
    if request.args.get("error"):
        return f"Campfire returned {request.args['error']}", 400
    if not pending or request.args.get("state") != pending["state"]:
        return "State mismatch", 400

    r = requests.post(
        f"{CAMPFIRE_API}/ca/oauth/token",
        auth=(CLIENT_ID, CLIENT_SECRET),
        data={
            "grant_type": "authorization_code",
            "code": request.args["code"],
            "redirect_uri": REDIRECT_URI,
            "code_verifier": pending["verifier"],
        },
        timeout=10,
    )
    r.raise_for_status()
    session["tokens"] = r.json()  # In production, store server-side, encrypted.
    return redirect(url_for("home"))


@app.get("/")
def home():
    tokens = session.get("tokens")
    if not tokens:
        return '<a href="/connect">Connect to Campfire</a>'
    r = requests.get(
        f"{CAMPFIRE_API}/users/api/get-user-permissions",
        headers={"Authorization": f"Bearer {tokens['access_token']}"},
        timeout=10,
    )
    if r.status_code == 401:
        return redirect(url_for("refresh"))
    return f"<pre>{r.text}</pre>"


@app.get("/refresh")
def refresh():
    tokens = session.get("tokens")
    r = requests.post(
        f"{CAMPFIRE_API}/ca/oauth/token",
        auth=(CLIENT_ID, CLIENT_SECRET),
        data={"grant_type": "refresh_token", "refresh_token": tokens["refresh_token"]},
        timeout=10,
    )
    if r.status_code != 200:
        session.pop("tokens", None)  # Connection is gone; the person must reconnect.
        return redirect(url_for("connect"))
    session["tokens"] = r.json()
    return redirect(url_for("home"))

​

Sign in with Campfire (OpenID Connect)

https://api.meetcampfire.com/ca/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyour-app.com%2Foauth%2Fcallback
  &response_type=code
  &scope=openid%20email%20profile%20invoices%3Aread
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

import jwt

jwks = jwt.PyJWKClient("https://api.meetcampfire.com/.well-known/jwks.json")

def verify_id_token(id_token: str, nonce: str) -> dict:
    key = jwks.get_signing_key_from_jwt(id_token).key
    claims = jwt.decode(
        id_token,
        key,
        algorithms=["RS256"],
        audience=CLIENT_ID,
        issuer="https://api.meetcampfire.com",
        options={"require": ["sub", "exp", "iat", "nonce"]},
    )
    if claims["nonce"] != nonce:
        raise ValueError("nonce mismatch")
    return claims

​

ID token claims

​

UserInfo endpoint

curl https://api.meetcampfire.com/auth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{"sub": "31017", "email": "jordan@example.com", "name": "Jordan Lee"}

​

Discovery

​

Part 3: Manage connections

​

Viewing connected apps

​

Disconnecting an app

{"detail": "OAuth app token is invalid or has expired."}

​

When access ends automatically

​

Part 4: Manage your app

​

Versions and approval

• Production is the version people authorize, and it’s what the app uses in every workspace.
• Development is your draft. There’s at most one. The first time you save a change on the Details or Permissions tab (or in the manifest’s app section), Campfire copies production into a new development version and saves your change there. Later saves update the same draft.

​

Testing a development version

• If production registers the redirect_uri, the person authorizes production. Production always wins when both match.
• If only the development version registers it, the person authorizes the draft, with the draft’s name, details and permissions. Development authorizations are limited to your own workspace.
• If neither does, the request is rejected.

​

Promoting

• Private apps are promoted immediately.
• Published or approved apps are submitted to Campfire for review. The button becomes Submit for approval, and the badge shows vN · Pending approval. You can keep testing the draft while it waits. Saving another change withdraws it from review, so you’ll need to submit again.
• If Campfire approves it, the draft becomes production.
• If Campfire requests changes, the badge shows vN · Changes requested, and the app page shows a banner with the reviewer’s message. Edit the draft and submit it again.

​

Rotating the client secret

​

Deleting

​

Private vs. published apps

​

Scopes reference

​

Errors and troubleshooting

​

Authorize endpoint

​

Token endpoint

​

API requests

​

Security checklist

• Keep the client secret on your server. Never put it in front-end code, mobile apps, or source control.
• Always send and verify state.
• Use PKCE (S256) on every authorization.
• When you use OpenID Connect, send a nonce, verify every ID token before trusting it, and key accounts on sub, not email.
• Request the fewest scopes you need. Prefer draft over write when a human should review changes.
• Store tokens encrypted, and save each new refresh token before using the new access token.
• Handle 401 by refreshing once, then prompting the person to reconnect.
• Rotate the secret immediately if it may have leaked. This also revokes every existing token.