Summary
Access to the Hybo API is done through OAuth 2.0 with delegated user tokens: every call is executed on behalf of an authenticated Hybo user, and the API applies exactly that user's permissions. There is no anonymous access.
For each integration, Hybo registers a dedicated application with its identity provider (Microsoft Entra External ID / B2C) and provides the credentials needed to obtain tokens. That application is the identity of the integration and the only supported access mechanism.
What Hybo provides
Item | Description | Format example |
Client ID | Identifier of the application registered for the client. | 11111111-2222-3333-4444-555555555555 |
Client Secret | Secret credential, delivered through a secure channel along with its expiration date. Renewal must be requested by the client before it expires. | xxx~yyyy... |
Authorization URL | Authorization endpoint of Hybo's identity provider. | |
Token URL | Token issuance endpoint. | |
Scope | Delegated permission that must be requested when asking for the token. | |
API base URL | Host against which calls are made, per environment. |
Authorization URL, Token URL, and Scope are stable and form part of the integration contract. Hybo will try to communicate any changes with sufficient notice (typically 30 days), except for urgent security-related changes or identity provider requirements, which may apply without prior notice.
Already have a custom access policy agreed with Hybo (for example, federation with your own identity provider)? The integration will use that same policy; the rest of the flow described here doesn't change.
What we need from you
Before setting up the integration, we need you to provide:
Redirect URI(s) of your platform or application. Common examples:
Power Automate / Power Apps (custom connector):
https://global.consent.azure-apim.net/redirectPostman (testing):
https://oauth.pstmn.io/v1/callbackYour own application: your backend or frontend's callback URL
Technical contact for credential delivery and notices (secret rotation, contract changes).
Brief description of the use case: which tool will call the API and for what purpose, so we can assign the appropriate permissions.
Only Redirect URIs that have been communicated and registered will work. Adding a new one requires requesting it from Hybo.
How the token is obtained and used
The enabled flow is OAuth 2.0 Authorization Code (delegated):
Your application redirects the user to the Authorization URL, requesting the provided Scope.
The user authenticates on the Hybo login screen with their usual account.
The identity provider returns an authorization code to the registered Redirect URI.
Your application exchanges the code for an access token (and a refresh token) at the Token URL, authenticating with your Client ID and Client Secret.
Every API call includes the token in the header:
GET /api/Parking/ZonesByContext HTTP/1.1 Host: api.{environment}.hybo.app Authorization: Bearer <access_token> Accept: application/json
Most platforms handle this flow automatically: in Power Automate it's configured once in the custom connector's Security tab and the connection handles the rest; in custom applications, standard libraries such as MSAL implement the full flow, including renewal.
Identity and permissions
The token belongs to the user: the API resolves the tenant, the user, their roles, and contexts from the token's claims. A userId or email sent in a request body does not replace the token's identity.
The integration can only do what the authenticated user can do. There is no privilege escalation.
The user must exist in Hybo and hold the roles corresponding to the module being used (for example, AppUser, ParkingAppUser for parking).
Token lifetime and renewal
Item | Behavior |
Access token | Short lifetime (approx. 60 minutes). Sent with every request. |
Refresh token | Managed by your platform (MSAL, Power Platform, etc.) to renew the access token without further user intervention. |
Expiration | A 401 Unauthorized response with a previously valid token usually indicates expiration: renew and retry. |
The API does not expose its own login or refresh endpoints; all token issuance and renewal happens against the identity provider.
Unattended integrations (scheduled flows, agents)
Processes that run without a user present (scheduled Power Automate flows, agent tasks, syncs) also use the delegated model: the connection is created once with a user, and subsequent executions use that user's identity.
Recommendation: create those connections with a dedicated service account (for example, [email protected]), set up in Hybo with strictly the necessary permissions, instead of an individual employee's personal account. This way the integration doesn't depend on any single person's lifecycle (departures, password changes, deactivations).
Generic access with application-only permissions (client credentials / app-only) is not part of the standard contract. Hybo has an application context available for a limited set of endpoints, aimed at simple read-only integrations or check-in-related actions. This mechanism is not enabled by default: if your integration needs it, contact Hybo to review the use case.
Credential lifecycle
The Client Secret expires (typical validity: 12–24 months). The exact expiration date is provided together with the credentials; it is the client's responsibility to request renewal from Hybo with enough notice (recommended: at least 15 days before expiration) to avoid interrupting the integration.
Replacing the secret means updating its value in the integration's configuration, with no code changes.
The secret must be stored securely (a secrets manager or the platform's protected configuration). It must not be included in source code, repositories, or plain-text communications.
If you suspect the secret has been compromised, contact Hybo immediately to have it revoked and reissued.
Hybo may disable a client's application when the contractual relationship ends or in cases of misuse, with immediate effect on access.
Support policy
The only supported access mechanism is the registered application provided by Hybo, through the OAuth flow described in this article. Integrations based on reusing session tokens from Hybo's own applications, or other mechanisms not described here, are not supported and may stop working at any time without notice.
Access is currently in beta: the available API surface and its conditions may evolve. Hybo will try to give sufficient notice (typically 30 days) of changes affecting existing integrations, except for urgent security-related changes or identity provider requirements, which may apply without prior notice.
Common setup errors
Symptom | Common cause | Solution |
redirect_uri mismatch during login | The Redirect URI used doesn't match the registered one. | Check the exact URI and request Hybo to register it if missing. |
AADB2C90205 or invalid scope error | Scope is misspelled or incomplete. | Use the Scope value exactly as provided. |
401 Unauthorized on all calls with correct login | The token doesn't include the expected audience. | Include Hybo's Scope in the authorization request, not only in the token request. |
401 after working for a while | Access token expired and renewal not configured. | Check the refresh token handling in your platform. |
403 Forbidden with a valid token | The user doesn't have the required role or context in Hybo. | Review the user's roles (e.g. ParkingAppUser) with the Hybo administrator. |
The flow works and then stops weeks later | Secret expired without requesting renewal, or the connection creator's account was disabled. | Request a new secret from Hybo or recreate the connection with the service account. |
Onboarding checklist
You send us:
Redirect URI(s) of your platform
Technical contact
Description of the use case and tool
Hybo provides you with:
Client ID
Client Secret (secure channel) with its expiration date
Authorization URL and Token URL
Scope
API base URL per environment
Test user and data, if applicable
Joint verification:
Login completed from your platform
First authenticated call with a 200 response
For any questions during the integration, contact your Hybo reference team.