Apps service (third-party applications)

/apps manages third-party applications: external software that authenticates Pantahub users through OAuth and asks for permission to act on their account within approved scopes. (Not to be confused with the device applications you deploy to devices — that's the Apps guide.) Concepts: Accounts, identity & tokens.

Scopes

GET /apps/scopes is public and lists every scope Pantahub offers. Scopes follow a <resource>[.readonly|.write|.change] pattern over the core resources — user, devices, objects, trails, metrics — plus all for complete access:

curl -s https://api.pantahub.com/apps/scopes

[
  {"id": "all",              "service": "prn:pantahub.com:apis:/base", "description": "Complete Access"},
  {"id": "devices.readonly", "service": "prn:pantahub.com:apis:/base", "description": "Read only devices"},
  {"id": "trails.write",     "service": "prn:pantahub.com:apis:/base", "description": "Write only trails"}
]

Applications can also define their own scopes (an id plus description without the base service PRN) for permissions internal to the app.

Register an application

Three fields are required:

• type — public or confidential, per RFC 6749 §2.1.
• redirect_uris — where the OAuth flow may send tokens/codes.
• scopes — the approved list the app may request from users.

curl -s -X POST https://api.pantahub.com/apps/ \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "type": "public",
    "redirect_uris": ["https://myapp.example.com/oauth2/cb"],
    "scopes": [
      {"id": "devices.readonly", "service": "prn:pantahub.com:apis:/base"}
    ]
  }'

The response assigns the app an id, a PRN, a generated nick and — for use in the OAuth flows — a secret.

Manage your applications

# list yours
curl -s https://api.pantahub.com/apps/ -H "Authorization: Bearer $TOKEN"

# fetch one
curl -s https://api.pantahub.com/apps/<app-id> -H "Authorization: Bearer $TOKEN"

# update (e.g. add redirect URIs or a custom scope)
curl -s -X PUT https://api.pantahub.com/apps/<app-id> \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "type": "public",
    "redirect_uris": ["https://myapp.example.com/oauth2/cb"],
    "scopes": [
      {"id": "all", "service": "prn:pantahub.com:apis:/base"},
      {"id": "programs.all", "description": "Read/write programs inside myapp"}
    ]
  }'

# delete
curl -s -X DELETE https://api.pantahub.com/apps/<app-id> \
  -H "Authorization: Bearer $TOKEN"

Once registered, the app takes part in the authorization flows of the auth service to obtain tokens that act on behalf of users within its approved scopes.

Endpoint reference

Try any of these live in the API Reference:

Endpoint	Reference
GET /apps/scopes	List scopes
POST /apps	Create app
GET /apps	List apps
GET /apps/{id}	Get app
PUT /apps/{id}	Update app
DELETE /apps/{id}	Delete app