Consume APIs with auth sessions
Introduction
Learn how to authenticate your users and take actions on their behalf.
Before you start this document, the following is recommended:
- Understand core Intuned concepts
- Understand Auth session types. Specifically, understand the difference between credentials-based auth sessions and recorder-based auth sessions and when to use each.
- Understand the development of an project with auth session enabled
Creating/managing auth sessions
To create an auth session, you must have the following:
- [Required] Access to user credentials, ether it is stored or the user is present
- [Optional] Proxy to the location you wish to have the user authenticate from
Auth sessions can be managed via the Intuned UI or via the API.
- The API provides a way to manage auth sessions programmatically. This is typically used when you are building an integration that has no APIs and you want to automate actions on behalf of your users (you need to provide credentials). Building a LinkedIn integration is a good example here. For API docs, you can look at the Auth Sessions API reference.
- The UI provides a simple way to create, update, and delete auth sessions. This is typically used when you are building an authenticated scraper or doing back-office automation with a limited set of auth sessions.
To learn more and dig deeper:
Utilizing auth Sessions
Calling an API in an project with auth sessions enabled requires an auth session to be present. Prior to executing any APIs, Intuned will check if the auth session is valid by attempting to call the auth-sessions/check API that is defined in the project.
After creating an auth session, it must be included in input payload of the direct API calls. If jobs or queues are being configured on an project with auth sessions enabled then the configuration must include auth session as well.
To learn more and dig deeper:
- Use authSession in the body to make an async call
- How to use auth sessions in job
- How to use auth sessions in a queue
Other aspects of auth session
Proxies
An auth session can be configured with a proxy to ensure all actions and traffic from the browser are showing up from the same IP address. Proxies are not required to use auth sessions but are commonly used depending on the target service.
Once an auth session is configured with a proxy, all API calls with this auth session will be routed via the proxy so if the proxy fails the API calls will fail as well. If there are failures in the proxy, you can update the proxy configured on an auth session.
Updating auth sessions
Once an auth session has been created, it should serve as the only auth session instance for that user/service pairing. For example is Sam created an auth session for Service A with the id sam-serviceA-sessionthen this auth session should be maintained and updated by you. This means that you must update and maintain the auth session for the duration you need it.