Authentication

Mango Power Open API uses the OAuth 2.0 Client Credentials Grant for server-to-server integrations. An Application Client represents an integration—not an individual user—and grants access to resources owned by one Mango Power organization.

How authentication works

An integration follows the same cycle throughout its lifetime:

1. Store the Application Client ID and Secret in your backend.
2. Exchange those credentials for a short-lived access token at POST /openapi/auth.
3. Send the token as a Bearer token when calling protected endpoints.
4. Reuse the token for its one-hour lifetime, then request a new one before it expires.

User login tokens and Open API access tokens belong to separate trust boundaries. An Open API token cannot be used with Mango Power user-facing APIs, and a user token cannot be used with /openapi/* endpoints.

Application Client credentials

Each Application Client belongs to one Mango Power organization. Its Client ID identifies the integration, while its Secret authenticates the integration.

Store the Secret in a server-side secret manager or protected environment variable. Avoid logging the Secret, the HTTP Basic Authorization header, or issued access tokens.

Token endpoint

Send the token request to your assigned regional API base URL.

Part	Value
Endpoint	POST /openapi/auth
Client authentication	HTTP Basic using the Client ID and Client Secret
Content type	application/x-www-form-urlencoded
Form body	grant_type=client_credentials and optional scope=openapi.read

The HTTP Basic username and password are the form-encoded Client ID and Secret. OAuth libraries and mature HTTP clients normally construct this header correctly. If you construct it yourself, form-encode each credential separately, join them with :, and Base64-encode the resulting bytes.

Do not send Client credentials in the request body, URL, browser code, mobile applications, or logs. Production requests must use HTTPS. Omitting scope defaults to openapi.read.

For the exact request and response schemas, headers, and endpoint-specific errors, see POST /openapi/auth in the API reference.

Using an access token

Send the access token on each protected request:

Authorization: Bearer <access_token>

Tokens currently carry the openapi.read scope and expire after one hour (3,600 seconds). No refresh token is issued. Your integration must renew the token proactively before expiration and use the replacement token for subsequent calls; do not wait for an expired-token response. Cache a token in your backend instead of requesting a new token for every API call.

Keep credentials and tokens within the region assigned to the Application Client. Do not automatically send them to another regional API hostname.

Handling authentication failures

Treat request and credential failures as configuration problems: correct the request or credentials before retrying. For temporary server failures, retry with exponential backoff and jitter. Record the response request_id when one is provided so Mango Power support can trace the request.

The API reference is the source for the exact HTTP statuses and error schemas. Protected business endpoints return registered business errors as HTTP 422 with stable numeric codes; see Error handling for the complete decision flow.

Credential lifecycle

• Resetting a Client Secret invalidates the old Secret immediately. Tokens issued before the reset remain valid until they expire.
• Disabling or deleting a client invalidates its issued tokens immediately.
• Removing the owning organization also invalidates the client’s issued tokens.

Use the production API hostname for the region assigned to the client. Credentials and data are region-bound; do not automatically fail over a request to another region.