Overview
iPaaS.com is API-first — everything you can do in our platform can be accomplished through API calls. Our database is accessed exclusively through the API, and our UI is entirely API-driven.
Important:
If you aren't familiar with working with an API and Swagger, you may experience the following issues:
Incorrect API Calls: Leading to errors, unexpected responses, or failure to retrieve and submit data.
Data Corruption or Loss: Improperly structured requests or misunderstanding of API operations could unintentionally modify or delete critical data or configuration.
System Instability: Malformed requests or excessive or improper API usage could impact system performance or availability.
Security Vulnerabilities: Misconfiguration or misunderstanding of authentication and authorization mechanisms could expose sensitive information.
Wasted Time and Resources: Significant time may be lost troubleshooting issues that stem from a lack of understanding of API principles and Swagger documentation.
Proceed with caution and ensure you have the necessary skills and understanding before interacting with this system.
The iPaaS.com API enables you to:
Subscribers: Manage subscriptions and mapping configurations, plus perform CRUD (Create, Read, Update, and Delete) operations.
Integrators: Manage private and certified integrations.
Managed integration Service Providers (MiSPs): Automate subscriber account relationships.
Key Points:
Role-based permissions are managed via API.
Authenticate using username/password or API tokens.
Tokens must be regenerated when roles or users are updated.
Environments
Select the appropriate base URL for your environment. All API calls — authentication and data — use the selected base URL.
Environment | Base URL |
Production |
|
Staging |
|
Development |
|
Base Paths:
Each iPaaS.com API also has its own base path that must be appended to the base URL. The full request URL follows this pattern:
{base_url}/{base_path}/v2/{endpoint}For example, the login endpoint lives on the SSO API. On production, that resolves to:
https://api.ipaas.com/sso/v2/Auth/Login
Refer to the Swagger documentation for each API to find its base path.
Authentication
Choose between two authentication methods:
Method 1: User Credentials
Since users operate across multiple companies, authorizations are maintained at the company level, not the user level. The login response includes a JWT access_token that already contains a CompanyId claim, so the user is automatically scoped to their default company. Steps 2 and 3 are only needed if the user wants to switch to a different company.
Authentication Flow:
User Login →
{base_url}/sso/v2/Auth/LoginProvide
email_addressandpasswordin the request body.Receive
access_token,refresh_token,access_token_expiration, and user id.
List Companies (optional) →
{base_url}/sso/v2/User/{id}/CompaniesUse the access token from step 1.
Returns the list of companies the user has access to.
Switch Company →
{base_url}/sso/v2/User/ChangeCompany/{id}Provide the
target company_idin the URL and the currentaccess_tokenin the Authorization header.Returns a new
access_token,refresh_token, andaccess_token_expirationscoped to the selected company. Replace all three stored values.
Example: Login Request
curl -X 'POST' \
'https://api.ipaas.com/sso/v2/Auth/Login' \
-H 'Content-Type: application/json' \
-d '{
"email_address": "user@example.com",
"password": "your_password"
}'
Example: Login Response
{
"id": 664,
"name": "User Name",
"email_address": "user@example.com",
"access_token": "eyJ...",
"access_token_expiration": "2026-05-13T17:53:12+00:00",
"refresh_token": "AQA...",
"permissions": [...]
}
Store these values after login:
access_token: sent in the Authorization header for all API calls.access_token_expiration: checked before each call to determine if a refresh is needed.refresh_token: used to obtain a new access token when the current one expires.id: the user ID, needed if listing companies.
Token Refresh
Access tokens are time-limited. When the current token expires, use the refresh_token to obtain a new one without requiring the user to log in again.
POST {base_url}/sso/v2/Auth/Refresh
Content-Type: application/json
{
"refresh_token": "AQA..."
}
The response returns a new access_token and updated expiration. Store both for subsequent calls.
Pass only the refresh_token to this endpoint. Do not include the expired access_token in the request body or headers.
Token Lifecycle Rules
Check expiration before each call. Compare the current time to access_token_expiration. If expired, refresh first, then make the call.
The token only needs to be valid when the call starts. A long-running request that begins with a valid token will complete successfully even if the token expires mid-call.
Do not refresh proactively. Avoid refreshing on a timer, before every batch, or every N records. Only refresh when the token has actually expired.
401 fallback. If a call unexpectedly returns 401 Unauthorized, refresh the token and retry the call once. If the retry also fails, surface the error.
ChangeCompany replaces all token values. After switching companies, use the new access_token, refresh_token, and access_token_expiration directly. No additional refresh call is needed.
Method 2: API Key
If your company has issued an API Key, it comes preconfigured with all approved company authorizations. If you need to create an API key, see API Keys in User & Role Management for details.
Making Authorized Requests
Once you have a valid access token, include it in your request headers:
curl -X 'GET' \
'https://api.ipaas.com/subscriptions/v2/Events?pageNumber=1&pageSize=100' \
-H 'accept: text/plain' \
-H 'Authorization: {your_access_token}'
Error Handling
Error Response Format: Error messages are returned as plaintext in the response body.
HTTP Status Codes
Code | Status | Description |
200 | OK | Successful request |
201 | Created | A new resource has been successfully created |
400 | Bad Request | Invalid JSON, missing required fields, or validation errors encountered |
401 | Unauthorized | Missing, invalid, or insufficient API token permissions |
404 | Not Found | The requested resource does not exist at the specified API |
429 | Too Many Requests | The rate limit was exceeded. See Working with API Rate Limits. |
5XX | Server error | There is an internal iPaaS.com server error |
Rate Limits
You may encounter 429 Too Many Requests errors in two scenarios:
Monthly API Limits: Based on your billing plan.
Plans with overage allowance: Additional charges apply beyond limits.
Plans without overage: API calls blocked after the limit is reached.
Volume Restrictions: Temporary limits when resources are overwhelmed.
The error message will specify whether the limit is monthly or volume-based.
Pagination
Pagination metadata is returned in the X-Pagination header as JSON. For example:
{
"total_Count":165,
"page_Size":100,
"current_Page":1,
"total_Pages":2,
"previous_Page":"No",
"next_Page":"Yes"
{ Metadata Fields:
total_Count:Total records availablepage_Size:Records per pagecurrent_Page:Current page numbertotal_Pages:Total number of pagesprevious_Page/next_Page:Navigation flags ("Yes"/"No")
Response Format
Successful requests: Return the requested, modified, or created data.
PUT/POST requests: Include the complete updated resource.
Error responses: Return error messages as plaintext.
API Versioning
Current Version: V2
Upcoming: V3 (backwards compatible with V2)
Compatibility: Currently, we do not expect to launch any API versions or endpoints that are not backwards compatible.