If there’s one thing that excites me as a developer, it’s the ability to push tools and platforms beyond their default limits. APIs are what make this possible. They act as the bridge that connects systems, unlocking powerful automation, seamless integrations, and giving me unparalleled control over workflows. In my experience, APIs aren’t just a technical tool — they’re the cornerstone of innovation, helping me create solutions that are both efficient and ready to adapt to whatever changes come next.
I’ve seen firsthand how APIs open doors to endless possibilities. Whether I’m streamlining complex workflows or experimenting with new integrations, APIs give me the power to break down barriers, connect systems, and transform data into actionable insights. They’ve become my go-to toolkit for crafting applications that not only work smarter but also scale effortlessly. In this guide, I’ll take you through my journey with the newly released ODC Rest APIs (User and Access Management API and Portfolio API) and show you how they can help elevate your projects to new heights.
Setting the Stage: What Makes APIs So Essential?
APIs are nothing new, but every time I work with them, I’m reminded of how transformative they can be. They’re not just a way to connect systems — they’re the backbone of automation, integration, and customization. When I use APIs, I’m not just building applications; I’m crafting interconnected ecosystems that run smarter and more efficiently.
For me, APIs stand out because they bring so much versatility to the table. Here’s what I love most about working with them:
Automation: They save me countless hours by automating repetitive tasks like user provisioning and deployment tracking. What used to take hours can now happen in seconds.
Integration: APIs let me connect external systems effortlessly, bridging the gap between tools and platforms to create seamless workflows.
Customization: They give me the flexibility to tailor workflows, user experiences, and backend processes to meet the unique needs of every project I take on.
With APIs, I can focus on building solutions that are not only functional but also optimized for the way I work. It’s like having a toolbox where every tool is designed to make my life easier.
Step 1: Getting Started with ODC Rest APIs
Before diving into the APIs themselves, it’s important to set up your environment correctly within the ODC portal. While it’s straightforward, skipping or misconfiguring these steps can lead to unnecessary headaches later on. Here’s how I get started:
1. Configure Your API Client
In the ODC portal, the API Client is your system’s unique identity — it’s how the platform recognizes and authenticates your application. Setting it up is a key first step:
Navigate to the API clients section in the ODC portal.
Click on “Create API Client” to open the setup form.
Provide a name for your client: This should be something descriptive that helps you identify the application later.
(Optional) Add a description: This is useful if you have multiple clients and need a quick reference for what this one does.
Set an expiration date for the client secret: By default, it’s set to expire in 90 days, but you can adjust this depending on your security policies. You can also enable email reminders to notify you before the secret expires.
The Stage selection is automatically set due to the inheritance of User management permissions. A quick reminder: users in ODC serve all stages, including Development, Test, and Production.
In the User Management section, choose the specific operations this API Client can perform.
Once everything is filled out, click “Create API Client”. The portal will generate a client secret for you, which you’ll need to securely store — this is what your application will use to authenticate requests.
2. Master OAuth 2.0
When working with ODC Rest APIs, secure authentication is non-negotiable — and that’s where OAuth 2.0 comes into play. This protocol ensures that only authorized applications can access the APIs, safeguarding sensitive data and operations. It’s straightforward once you understand the flow, but how OAuth 2.0 Works?
To authenticate API calls, I need an access token, which I obtain by exchanging my client credentials — Client ID and Client Secret (generated in the previous step). Think of this token as a temporary key — it grants my application secure, time-limited access to the APIs. Every API request I make includes this token in the authorization header, ensuring that only authorized applications can interact with the system. Access tokens are critical for keeping interactions secure, but they also require careful management. I always make sure to:
Store tokens securely to prevent unauthorized access.
Monitor token expiration and refresh them as needed to avoid interruptions.
But where do I get the token from? Which URL do I need to use?
3. Understand OIDC Discovery
When working with ODC Rest APIs, secure authentication is essential and OAuth 2.0 is the protocol that facilitates this. One of the key steps in this process is understanding and using the OpenID Connect (OIDC) Discovery mechanism. This simplifies authentication by providing the necessary endpoints and metadata for interacting with the authorization server. Here’s how I approach it:
Understanding the Process
To access the APIs, I need to obtain an access token using my client credentials (client ID and client secret) like I mentioned before. The OIDC Discovery document simplifies this process by offering a centralized source for all relevant authentication information. Here’s the workflow I follow:
1. Obtain the Discovery Document:
I start by retrieving the OIDC Discovery document, which provides the necessary endpoints for authentication. This is done by sending a GET request to the .well-known endpoint of my ODC portal domain:
curl -X GET "https://<ODC_PORTAL_DOMAIN>/identity/.well-known/openid-configuration" -H "accept: application/json"Replace <ODC_PORTAL_DOMAIN> with your organization’s domain.
2. Retrieve the Token Endpoint:
From the Discovery document, I extract the token_endpoint value. This endpoint is where I’ll send my request to obtain an access token.
3. Request the Access Token:
With the token endpoint and my client credentials, I send a POST request to fetch the access token:
curl -X POST "<TOKEN_ENDPOINT>" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>"Replace <TOKEN_ENDPOINT>, <CLIENT_ID>, and <CLIENT_SECRET> with the appropriate values.
If the credentials are valid, the authorization server responds with an access token:
{ "access_token": "ACCESS_TOKEN", "expires_in": 43200, "token_type": "Bearer"}The expires_in value indicates the token’s validity period in seconds (e.g., 12 hours).
Best Practices
Managing access tokens responsibly is crucial:
Secure Storage: Store tokens securely to prevent unauthorized access.
Monitor Expiration: Tokens are valid for 12 hours, so I always request a new token before the current one expires to maintain uninterrupted access.
By following these steps and leveraging the OIDC Discovery mechanism, I establish a secure and efficient authentication flow, allowing my application to interact seamlessly with ODC Rest APIs.
Step 2: Explore the Core APIs
With the setup complete, it’s time to dive into the APIs and see what they can do. For me, mastering the core APIs is where the magic happens — they’re the tools that turn everyday tasks into seamless, automated processes. Here are the key ones I recommend starting with:
1. User and Access Management API
Managing users and roles is critical to the success of any application, and this API makes it both efficient and flexible. Here’s how I use it:
Automate user provisioning and deprovisioning: Adding or removing users no longer needs to be a manual process.
Assign roles dynamically: With business logic driving role assignments, I can ensure users always have the right access.
Enhance security: This API helps me enforce strict access controls, ensuring only the right people have access to sensitive areas of the application.
Here is the link for the OpenAPI spec.
2. Portfolio API
If you’re managing multiple applications, the Portfolio API is a must-have. Similar to the Lifetime API in OS11, in this 1st version, it provides an organized way to keep track of your application portfolio by allowing you to retrieve the information about assets and environments. More to come (I hope :D)
Here is the link for the OpenAPI spec.
Step 3: Respect the Boundaries
When working with APIs, it’s critical to be aware of rate limits. These limits ensure fair usage across all users and help maintain the performance of the platform. OutSystems enforces global rate limits per organization, which vary based on the API domain. Understanding these limits can help you plan your API usage and avoid hitting unnecessary roadblocks.
How Rate Limits Work
Here’s a breakdown of the current rate limits for OutSystems APIs:
User and Access Management: 100 requests per minute.
Portfolio Management: 100 requests per minute.
Bulk User Create API: Limited to 5 requests per minute.
If you exceed the rate limit, the server will return a 429 Too Many Requests response, signaling that your application needs to pause and retry after some time.
Tips for Staying Within the Limits
To avoid throttling and ensure smooth operation, I use the following strategies:
Prioritize critical requests: I ensure high-priority operations are executed first to make the most of the allocated request limits.
Batch operations: Where possible, I combine multiple actions into a single request to reduce the number of calls.
Implement retry logic: If my application encounters a 429 Too Many Requests response, it automatically waits and retries the request after the cooldown period.
Step 4: Secure Your Integration
APIs are incredibly powerful tools, but with that power comes great responsibility. Ensuring the security of your integrations isn’t just about protecting your data — it’s about maintaining trust and the reliability of your applications. Over time, I’ve learned that following a few key best practices goes a long way in keeping everything secure.
1. Rotate Credentials Regularly: Avoid reusing the same client secret indefinitely. Regularly updating your credentials reduces the risk of misuse, especially if a key is accidentally exposed or compromised.
2. Use Least Privilege: Only grant your API Client the permissions it absolutely needs. By limiting access to specific environments and operations, I minimize potential damage in case of an issue.
3. Monitor Access Patterns: Keep an eye out for unusual activity or unauthorized access attempts. Logging API usage and reviewing it periodically helps me catch anomalies early, ensuring I stay ahead of potential threats.
By implementing these strategies, I’ve been able to maintain secure integrations while minimizing risks.
Real-World Use Cases
APIs shine when applied to real-world challenges, and the ODC Rest APIs are no exception. Here are a few practical ways I’ve seen them transform workflows and simplify everyday tasks:
1. Onboarding Automation
The User and Access Management API is a game-changer for automating onboarding. When a new employee joins, I can instantly create their user account, assign roles dynamically, and grant them the exact permissions they need — all without manual intervention. This streamlines the onboarding process, reduces errors, and saves time for both IT teams and managers.
2. Portfolio Insights
With the Portfolio API, keeping tabs on active applications has never been easier. I use it to monitor my team’s entire application portfolio in real-time, ensuring no app falls through the cracks. Whether it’s tracking updates, categorizing applications, or generating quick overviews for stakeholders, this API keeps everything organized and accessible.
3. Dynamic Workflows
By integrating ODC APIs with third-party tools, I’ve been able to build workflows that adapt to business needs in real-time. For example, combining these APIs with automation platforms or custom scripts allows me to trigger specific actions based on predefined conditions, creating a responsive and efficient system that evolves with my projects.
A Developer’s Edge
For me, the ODC Rest APIs aren’t just tools — they’re enablers. They empower me to:
Build smarter, more efficient systems with less manual effort.
Seamlessly integrate applications into the broader tech ecosystem.
Deliver solutions that are dynamic, responsive, and secure.
By following the steps I’ve outlined in this guide, you’re well on your way to mastering these APIs and taking your applications to the next level. Whether it’s automating workflows, managing user access, or gaining deeper insights into your portfolio, the possibilities are endless.
So, what’s stopping you? Dive into the documentation, start experimenting, and let your creativity take flight. With the ODC Rest APIs, the only limit is your imagination.
