Partner Apps

A partner app is a listing in the Monta marketplace that operators can install. Installing it
grants your app scoped access to that operator's data, authenticated with OAuth 2.0.

Use a partner app when you are building an integration that multiple Monta operators will adopt.
For a single-operator integration you manage yourself, the direct API consumer credentials are
simpler.

Lifecycle

Receiving your credentials

On approval, Monta emails the address on your publisher organization. The email contains a
single-use link that reveals your oauthClientId and oauthClientSecret.

• The link may be opened once. Store the secret in a secret manager the moment you see it.
• The client secret is never returned by any API, and never re-sent by email.
• If the link is consumed or lost, contact Monta support. Re-issuing mints a new OAuth client;
  the previous credentials stop working and any operator who authorized against them must
  re-authorize.

Redirect URIs

Register every callback URL your app will use, one per environment.

• https only, except loopback (localhost, 127.0.0.1, [::1]) for local development.
• Matched exactly: https://example.com and https://example.com/ are different URIs.
• No wildcards, no URL fragments, no private or internal IP addresses.
• Up to 10 per app, no duplicates.

Get these right at submission. See Going live for the full authorization flow.

Scopes

An app requests scopes at registration, in resource:permission form — for example
teams:read, charge-points:read. The operator sees them at install and consents to them as a set.

offline_access is requested per authorization, not at registration, and is what returns a
refresh token.

An access token is limited to the intersection of the app's registered scopes, the operator's
consent, and the scopes named in the authorize request.

Webhooks

Partner apps involve two separate webhook mechanisms with two separate secrets. They are easy to
confuse.

App lifecycle webhooks

Monta notifies your app when an operator installs it (and on other lifecycle events).

• Configure a webhook URL and a webhook secret on the app itself.
• The secret is not generated for you. You supply it, minimum 16 characters, and it must be
  set whenever a webhook URL is set — a URL without a secret is rejected.
• If your app has no webhook URL, the secret is null and no lifecycle callbacks are delivered.
  This is expected, not an error.
• Payloads are signed with HMAC-SHA256 using that secret. Verify the signature before acting.

Event webhooks

Delivery of charge, team, and other domain events for an installed operator.

• Configured per install, with its own URL and secret.
• If you do not supply a secret, one is generated for you (16–191 characters).
• These are the webhooks described under Webhooks in this documentation.

Setting one does not configure the other.

Checklist before going live

• Redirect URIs registered for every environment, exact strings confirmed.
• Client secret stored in a secret manager, never in source control.
• Token exchange happens within 60 seconds of receiving the code.
• Refresh tokens persisted and rotated — the new one replaces the old on every refresh.
• Monta-Version header pinned on every API request.
• Webhook secret set if you configured a webhook URL, and signatures verified.
• state sent on authorize and validated on callback.