Apps & OAuth

Software that serves many farms? Create an app: each farm clicks Allow, you get tokens limited to what that farm granted. Serving only your own farm? An API key is enough.

	API key	App (OAuth)
Who creates it	The farm owner, in the app	You, in My apps
For	One farm	Many farms — each one consents
Credential	`nfk_…`	App ID `nfa_…` + App Secret `nfs_…` ⇒ Access token 15′
Review	None	None: Development mode ≤ 3 of your farms; Publish = automatic checks

Create the app

Open My apps › Create app — pick Use cases, get the App ID + App Secret right away (the secret is shown once). The app starts in Development mode: you and your app members can install it into up to 3 farms.

Let farms install — the install link returns a code

Put the install link behind a "Connect NextFarm" button. The farm picks scopes, clicks Allow and is sent back to your Redirect URI with a code (60 seconds, single use) and your state.

Install link

https://app.nextfarm.vn/vi/workspace/manage/apps/install?client_id=nfa_…&redirect_uri=https://abc.vn/nextfarm/callback&state=<state>

After consent the browser returns to

https://abc.vn/nextfarm/callback?code=nfc_7Qx…&state=<state>

Exchange the code for a token + workspace_id (server side)

Check the state matches, then exchange the code with your App Secret. Store workspace_id — that is the farm that just installed.

POST /api/v1/iam/oauth/token

curl -X POST https://api-prod.nextfarm.vn/api/v1/iam/oauth/token \
  -d grant_type=authorization_code \
  -d code=nfc_7Qx… \
  -d redirect_uri=https://abc.vn/nextfarm/callback \
  -d client_id=nfa_… -d client_secret=nfs_…

Returns

{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 900,
  "scope": "harvest.harvest.view harvest.trace.view", "workspace_id": "6b0e6dae-…" }

Redeeming a code twice ⇒ invalid_grant and every token from that install is revoked (a sign the code leaked).

Later tokens: client_credentials

Tokens live 15 minutes. Request new ones with App ID + App Secret + the stored workspace_id.

Example

curl -X POST https://api-prod.nextfarm.vn/api/v1/iam/oauth/token \
  -u "nfa_…:nfs_…" \
  -d grant_type=client_credentials \
  -d workspace_id=6b0e6dae-…

Call the API

curl https://api-prod.nextfarm.vn/api/v1/harvest/harvest-records?page_size=5 \
  -H "Authorization: Bearer eyJ…"

Test Console

In your app › Test Console: Generate Access Token for an installed farm (minted by NextFarm, the App Secret never reaches the browser), try calls with the embedded API Explorer, rebuild the sample farm, send a test app.ping.

Publish

Click Publish: the 12-item Publish checklist runs (profile + logo + description ≥ 50 chars, support mailbox receives mail, website + Privacy Policy reachable, https Redirect URIs, Webhooks answer 2xx to app.ping, scopes in the catalog, ≥ 20 successful calls across ≥ 3 operations in 7 days, 4xx < 30%, verified account ≥ 3 days, not reported / suspended). Pass everything and you are Live immediately (Auto-checked) — no human review. Verified by NextFarm is added by NextFarm for contracted partners.

Details

Granted scopes = requested ∩ the machine catalog ∩ what the installer holds. No scope controls devices or administration.
Adding scopes in Use cases ⇒ installed farms keep the old ones until they re-consent. Removing a scope ⇒ the next token loses it immediately.
Uninstall, scope change, app deletion or suspension ⇒ live tokens are blocked immediately (401 token_revoked).
Rotating the App Secret: the old secret keeps working for 24 hours.
Rate limit 600 calls/minute per app × farm; Rate limit.
Install events (app.installed …) and data events go to your app's Callback URL: Webhooks.

Error	Meaning
`400 invalid_grant`	code wrong / older than 60 s / reused / redirect_uri mismatch
`401 invalid_client`	Wrong App ID / App Secret or the app is suspended
`403 access_denied`	The farm has not installed / removed the app
`403 invalid_scope`	Asked for a scope the farm did not grant

Keep the App Secret on your server — never in a mobile app or browser code.

Full security rules: Security →