The functionality in this article is set to be released in an upcoming update.
The Integration API page in Client Settings lets Admins manage up to 10 named API keys and turn on Use modern authentication, so several integrations can authenticate and stay connected at the same time. This article explains how to prepare your integrations before turning on Use modern authentication, what the setting changes, and how to add, edit, and delete API keys. These capabilities are available only to Portals that already have Integration API access enabled.
Before You Turn On Use Modern Authentication
Use modern authentication changes how Absorb accepts access tokens from your integrations. Once it is on, every Integration API request must send its access token in an Authorization header using the Bearer scheme: Authorization: Bearer <token>. Whether you need to prepare first depends on whether any integrations are already calling the Integration API for your Portal.
Use modern authentication takes effect on the next API request. Any integration that is not already sending Authorization: Bearer <token> stops working immediately, including integrations holding tokens that were issued before the change. The only warning Absorb displays is a single confirmation dialog.
If You Have Integrations Already Running
The change each integration needs is made inside the integration itself, either in its code or in the connection settings of the middleware or automation tool that calls Absorb. This change cannot be made from Absorb, and the Admin who turns on the setting usually cannot make it alone. Work with whoever maintains each integration and complete the following steps in order:
- List every integration that authenticates against the Integration API for your Portal.
- Check how each integration sends its access token. It must use an Authorization header with the Bearer scheme, exactly as follows:
Authorization: Bearer <token>. - Have the owner of each integration that does not already use this format update it.
- Verify that each updated integration works as expected.
- Turn on Use modern authentication only after every integration has been updated and verified. For steps, see Turn On Use Modern Authentication below.
If You Are Building Your First Integration
If no integration is calling the Integration API for your Portal yet, there is nothing to break and nothing to migrate. Turn on Use modern authentication first, then build your integration to send Authorization: Bearer <token> from the start. Any integrations you add later can join the existing ones without disturbing them.
Turning the Setting Back Off
Use modern authentication is reversible, and turning it off is the recovery path if something breaks. Turning the setting off restores access immediately, and no confirmation is required. Access tokens that were already issued continue to work until they expire naturally, up to 4 hours.
If an integration stops working after you turn the setting on, turn it off, have the integration updated to use the Bearer scheme, verify the update, and then turn the setting on again.
Who Can Use This Feature
The Integration API card appears in Client Settings only for Portals that already have Integration API access enabled. This feature does not change which Portals have Integration API access. The following conditions also apply:
- Required Permission: The System Admin role is required, which is the same permission used for other Client Settings pages. No support ticket is required.
- Learner Visibility: This feature is entirely Admin facing. Learners have no visibility into it.
- Scope: Settings apply Portal wide and cannot be targeted to specific Departments.
- Licensing: No additional license or purchase is required.
How API Keys and Modern Authentication Work Together
When Use modern authentication is off, each new authentication cancels the access token that was issued before it. As a result, when two or more integrations run at the same time, only the most recent one to authenticate has a valid token, and the others are silently logged out. This happens even when the integrations share the same API key.
Use modern authentication is what fixes this. When it is on, each integration holds its own access token, and multiple tokens stay valid at the same time. The setting works with your existing single API key, so you don't need to create additional keys. Multiple API keys are optional and let you give each integration its own labeled credential that you can rename or delete without affecting the others.
Creating additional API keys does not, by itself, stop integrations from logging each other out. If Use modern authentication is off, only the most recently authenticated integration keeps a valid token, no matter how many keys your Portal has.
The following terms are used throughout this article:
Term |
Description |
| Integration API Key | A credential for the Integration API that identifies which Portal a request belongs to. A Portal can have up to 10 keys at once. |
| Default Key | The original key every Portal starts with. It can be renamed but never deleted. |
| Use modern authentication | The setting that lets several access tokens stay valid for your Portal at the same time, instead of each new token canceling the last. It works with any number of API keys, including one, and is off by default. |
| Bearer Scheme | The Authorization: Bearer <token> request format. It is required for all of your integrations once Use modern authentication is on. |
What an Integration Can Access
An API key does not carry permissions of its own. It only identifies which Portal a request belongs to. What an integration can access is determined by the Admin credentials used to authenticate, and the resulting access token carries that Admin account's permissions.
For more information about Admin permissions, see Admin Roles & Permissions.
Access the Integration API Page
The Integration API page is available from the Client Settings page in the Admin Experience (AE). To open it, follow these steps:
- Log in to the AE using your Admin account.
- Click your Account icon in the top-right corner of the page.
- Click Client Settings.
- Click the Integration API card.
The Integration API page contains the Use modern authentication setting and the API keys table. It also displays the OAuth client ID and OAuth client secret, which belong to a separate feature and are not covered in this article.
For more information refer to Absorb Integration API with OAuth 2.0.
Turn On Use Modern Authentication
If your Portal has integrations already running, complete the steps in Before You Turn On Use Modern Authentication first. Portals with no live integrations can turn the setting on right away. To turn on Use modern authentication, follow these steps:
- Open the Integration API page.
- Click the Use modern authentication toggle.
- Review the confirmation dialog.
- Confirm the dialog to turn on the setting.
To turn the setting off, click the toggle again. No confirmation is required, and tokens that were already issued continue to work until they expire.
Manage API Keys
The API keys table on the Integration API page lists every key for your Portal, with its Name, Description, and Key value. Use the Actions column to edit or delete a key.
Add an API Key
Add a key when you want an integration to use its own credential. Naming each key after the integration it belongs to makes the table easier to manage later. To add a key, follow these steps:
- On the Integration API page, click Add API key.
- In the New API key dialog, enter a Name for the key. This field is required and accepts up to 255 characters.
- Optionally, enter a Description of up to 1,000 characters.
- Click Save.
Absorb generates the key value when you save, and the new key appears in the API keys table. The key value is read-only and cannot be entered or edited. If Use modern authentication is on, make sure the integration using the new key sends its access token using the Bearer scheme.
Edit an API Key
You can update a key's name or description at any time without recreating the key. To edit a key, follow these steps:
- In the API keys table, click the edit icon in the Actions column for the key.
- Update the Name or Description.
- Click Save.
Delete an API Key
Delete a key when the integration that uses it is retired. Deleting a key does not affect any other key or the connections of integrations that use other keys. Before you delete a key, confirm that no active integration still depends on it. To delete a key, follow these steps:
- In the API keys table, click the delete icon in the Actions column for the key.
- Review the warning.
- Confirm the deletion.
The default key cannot be deleted. Its delete action is disabled, and a tooltip explains that the first API key is required to keep integrations running. To relabel the default key, edit its name instead.
API Key Limits
Each Portal can have up to 10 API keys, and this limit cannot be raised. When your Portal reaches the limit, the Add API key button is disabled, and a tooltip explains why. If you run more than 10 integrations, share keys across integrations or reuse keys from retired integrations.
Regenerating or rotating an existing key and viewing usage for individual keys are not currently available.
Common Scenarios
The following scenarios show how Use modern authentication and multiple API keys work in practice:
| Scenario | Setup | Result |
| Several processes share one key | Each integration, such as a data sync tool, a scheduling tool, and a custom enrollment job, is updated to send the Bearer header. The Admin then turns on Use modern authentication. No new keys are created. | Every process gets its own access token, and all of them stay valid at once. This alone solves integrations logging each other out. |
| Each integration has its own key | The Admin creates one named key for each integration, such as a Human Resources Information System (HRIS) sync, a compliance enrollment feed, and a reporting job. After all three integrations send the Bearer header, the Admin turns on Use modern authentication. | All three integrations hold independent sessions at the same time, and each key can be renamed or deleted without affecting the others. |
| First integration | The Admin turns on Use modern authentication before anything is built, optionally adds a named key, and builds the integration to send Authorization: Bearer <token> from the start. |
The Portal is set up correctly from day one, with no migration required. Later integrations join without disturbing existing ones. |
| Multiple keys with the setting off | The Admin creates a separate key for each integration but leaves Use modern authentication off. | Nothing improves. Only the most recently authenticated integration has a valid token, and the others are silently logged out. |
Troubleshooting
The following table describes common issues with API keys and Use modern authentication, along with how to resolve them:
| Issue | Cause | Resolution |
| An integration fails authentication immediately after Use modern authentication is turned on. | The integration is not sending its access token using the Bearer scheme. Enforcement applies to every request, not only to new logins. | Turn Use modern authentication off to restore access immediately. Have the integration updated to send Authorization: Bearer <token>, verify it, and then turn the setting back on. |
| Integrations still log each other out after additional keys are created. | Use modern authentication is off. Separate keys do not stop one access token from canceling another. | Prepare your integrations, and then turn on Use modern authentication. |
| The delete action for a key is disabled. | The key is the default key, which cannot be deleted. | Rename the default key if it needs relabeling, or create additional keys for new integrations. |
| A new key cannot be saved, and a message appears on a field. | The Name is empty or exceeds 255 characters, or the Description exceeds 1,000 characters. No key is created. | Enter a name or shorten the value, and then click Save again. |
| The Add API key button is disabled. | The Portal has reached the 10-key limit. | Delete a key that belongs to a retired integration, or share an existing key across integrations. |
| The Integration API card does not appear in Client Settings. | The Portal does not have Integration API access enabled, or the Admin does not have the Edit Client permission. | Confirm your permissions. To discuss Integration API access, work with your Absorb account team. |
Frequently Asked Questions
Expand the following questions for answers about API keys and Use modern authentication.
Why did my other integration get logged out when I connected a new one?
When Use modern authentication is off, each new authentication cancels the previously issued access token, so only the most recent integration stays connected. Turning on Use modern authentication lets each integration keep its own valid token.
Do I need multiple API keys to fix this?
No. Use modern authentication fixes the problem even with a single API key. Multiple keys are optional and let you separate and label integrations individually.
What must change before I turn on Use modern authentication, and who makes the change?
Every integration already calling the Integration API must send its access token as Authorization: Bearer <token>. The change is made by whoever maintains each integration, in its code or in the connection settings of the tool that calls Absorb. It cannot be made from Absorb.
I'm building my first integration. What should I do?
Turn on Use modern authentication first, and then build your integration to send the Bearer header from the start. With nothing live yet, there is nothing to migrate.
Why isn't Use modern authentication turned on automatically for every Portal?
The Integration API currently accepts an access token sent with any authentication scheme, or none at all, and many existing integrations rely on this. Turning the setting on for every Portal without warning would break those integrations immediately. Turning it on is optional, and Portals that leave it off continue to work as they do today.
Do multiple keys and modern authentication apply to other Absorb APIs?
No. Both capabilities apply only to the Integration API. They do not extend to other APIs, such as SCIM or Infuse.
I don't see the Integration API card. How do I get it?
The card appears only for Portals that already have Integration API access enabled. Enabling access is a separate process that this feature does not change. To discuss Integration API access, work with your Absorb account team.
Related Articles
For more information about the Integration API and Client Settings, see the following articles:
- Getting Started with the Absorb Integration API
- Absorb Integration API with OAuth 2.0
- Integration API Glossary
- The Client Settings Page
Comments
Article is closed for comments.