OAuth 2.0 Integration Guide

Use this guide to implement the OAuth handshake that lets Monta operators grant your Partner app access to their data.

Use a Partner app when

• You build an integration that many Monta operators can install.
• You need each operator to explicitly grant your app scoped access to their data.
• You plan to distribute the app publicly in the marketplace or to a targeted operator allowlist.

The moving parts

One app can have many installs. Your client credentials are per-app and long-lived, while access to an operator's data is per-install and that operator can revoke it without affecting other installs.

Onboarding

1. Submit your app with its name, description, requested scopes, redirect URIs, and webhook URL.
2. Wait for Monta to review and approve the app.
3. Open the one-time reveal link sent to your registered contact address and store the credentials.

The reveal link shows these values once:

• client_id
• client_secret
• webhook_secret — the HMAC key for verifying webhook deliveries

Your client is registered as a confidential client:

Start the authorization flow

The operator starts the flow from Monta Hub. They find your app in the catalogue, select Connect, and Monta builds the authorization request before redirecting their browser to Monta's identity provider.

Do not construct the authorization URL or add a “Connect with Monta” button in your product. Your only inbound surface is your registered redirect_uri.

End-to-end sequence

When the operator approves access, Monta creates the install and its consumer before redirecting to your app. Monta also binds the install, operator, and consumer identifiers to the token session, allowing the Partner API to resolve the token to the correct operator.

Redeem the code

Redeem the authorization code immediately in your callback handler:

curl -X POST {issuer}/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=ory_ac_... \
  -d redirect_uri=https://your.app/callback \
  -d client_id=<your_client_id> \
  -d client_secret=<your_client_secret>

A successful response includes an access token and its granted scopes:

{
  "access_token": "ory_at_...",
  "refresh_token": "ory_rt_...",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "charge-points:read charge-transactions:read offline_access"
}

Refresh the token

Refresh before the access token's one-hour expiry:

curl -X POST {issuer}/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token=ory_rt_... \
  -d client_id=<your_client_id> \
  -d client_secret=<your_client_secret>

Refresh tokens rotate: each response contains a new refresh_token and invalidates the previous one. Always persist the newest value. Replaying an already-used refresh token revokes the whole chain, and the operator must then re-install.

offline_access is added by Monta rather than requested by your app. It appears on the operator's consent screen and in your token response's scope, and it is what allows Monta to issue a refresh token. On its own it grants no access to data.

Call the Partner API

curl {partnerApiBaseUrl}/charge-points?perPage=50 \
  -H "Authorization: Bearer ory_at_..."

• Use /api/v1 as the base path. See the API Reference for available endpoints.
• Treat access tokens as opaque bearer strings. They have an ory_at_ prefix, but are not JWTs and must not be decoded or validated locally.
• Monta introspects each token, resolves it to the operator's consumer, and enforces consumer status, re-authorization requirements, and granted scopes.

Scope format: resource or resource:permission, where permission is read, write, or delete. For example: charge-points:read and teams:write. A bare resource is read-only. Request resource:write or resource:delete explicitly if you need more. Request the narrowest scopes you need because the operator sees the exact list during consent.

Rate limits: Each install has its own budget of 1,000 requests per 60 seconds by default. Traffic from one operator cannot exhaust another operator's limit.

Handle scope changes

If you later request additional scopes, existing installs are not upgraded automatically. Monta flags each affected install, and API calls return HTTP 403 with NEEDS_REAUTH:

{
  "errorCode": "NEEDS_REAUTH",
  "message": "Re-authorisation required for install 41 after a scope change",
  "context": {
    "install_id": 41,
    "reauth_url": "https://…/41/reauth"
  }
}

Handle NEEDS_REAUTH separately from other 403 responses: stop calling the API for that install, show the re-authorization state in your product, and send the operator to reauth_url. After the operator grants consent again, your existing tokens work with the widened scopes. Narrowing scopes does not trigger re-authorization.

Verify webhooks

Verify every delivery before parsing its body:

• Read X-Monta-Signature: sha256=<hex>.
• Calculate HMAC-SHA256 over the raw request body with your webhook_secret.
• Compare signatures in constant time.
• Use the signed delivered_at epoch timestamp to reject stale or replayed deliveries.

import hashlib
import hmac

expected = "sha256=" + hmac.new(
    secret.encode(), raw_body, hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, request.headers["X-Monta-Signature"]):
    abort(401)

Your endpoint must use HTTPS, be publicly resolvable, and return a 2xx response within 10 seconds.

Handle revocation and uninstall

• An operator can uninstall at any time. Monta revokes the install, disables its consumer, and sends install.revoked.
• Existing access tokens for that install stop working.
• Your app-level client_id and client_secret remain valid, and other operators' installs continue to work.
• Only one active install can exist for an app and operator. A re-install creates a new install with a new identifier.

Security summary

Endpoints

The OAuth handshake exists in production only. See the sandbox guidance at the top of this page before you begin certification.

For sandbox endpoints and the credential exchange used there, see Building in the sandbox.

Troubleshooting

Monta performs webhook replays, credential re-issues, and operator-allowlist expansions for you. Contact SUPPORT_CHANNEL_TO_FILL to request these operations.

Integration checklist

• Store the client credentials and webhook secret from the reveal link.
• Register the deployed HTTPS redirect_uri exactly.
• Redeem the authorization code immediately within the one-minute window.
• Handle refresh-token rotation and always persist the newest refresh token.
• Treat access tokens as opaque strings.
• Verify each webhook signature in constant time before parsing its body, and check delivered_at.
• Return 2xx from the webhook endpoint in under 10 seconds.
• Handle 403 NEEDS_REAUTH separately from other 403 errors.
• Stop all use of an install after install.revoked.
• Respect the 1,000 requests per 60 seconds, per-install limit and apply backoff.
• Reconcile state without depending solely on webhook delivery.