User Provisioning (SCIM) with Okta: Create and Remove Aligned Users Automatically

User Provisioning (SCIM) connects Aligned to your identity provider so that Aligned accounts appear and disappear automatically as people join and leave your organization. SCIM stands for System for Cross-domain Identity Management, the standard that identity providers such as Okta and Microsoft Entra ID use. Assign someone to Aligned in your identity provider and Aligned creates their account with the role you mapped, remove them and Aligned cuts their access immediately, moving their rooms and content to a colleague you choose. User Provisioning (SCIM) requires Single Sign-On (SSO) on your Aligned account first.

Prerequisites

Plan: Enterprise
Role: Admin
Technical: Single Sign-On (SSO) configured on your Aligned account. Without Single Sign-On, your identity provider has nowhere to accept the connection values.
Technical: Admin access in both Aligned and your identity provider.

1. User Provisioning (SCIM) vs. Single Sign-On (SSO)

User Provisioning (SCIM) and Single Sign-On (SSO) solve different problems, and you configure them separately. Single Sign-On controls how people log in to Aligned. User Provisioning controls whether an Aligned account exists at all. Configure Single Sign-On first, because User Provisioning depends on it.

	User Provisioning (SCIM)	Single Sign-On (SSO)
Best for	Creating and removing accounts automatically as staff join and leave	Letting people sign in to Aligned with your company credentials
Key difference	Manages account lifecycle and roles	Manages authentication only
Available on	Enterprise only	Enterprise only

2. Setting up User Provisioning

Setting up User Provisioning (SCIM) takes five tasks:

Copy two values from Aligned.
Choose who gets a leaver's content.
Paste the two values into your identity provider.
Map your roles.
Confirm the connection works.

Generating a new API token, in 2.2, is only needed if the original was never copied or has been lost.

2.1 How to get your connection details from Aligned

Your connection details are the SCIM connector base URL and the API token, and both live in the Aligned Admin Center.

Navigate to Settings → Admin Center → Integrations.
Locate User provisioning (SCIM) under Security & Privacy.
Click Enable.
Click Copy next to the SCIM connector base URL. This value is not a secret, so you can copy it at any time.
Click Copy next to the API token and store it somewhere safe before you continue.

Copy the API token before you refresh or leave the page. Each token can be copied once: after you copy it the button changes to Generate new token, and refreshing the page without copying loses the value too. Generating a new token gives you a fresh value with its own Copy button - see 2.2.

The same window also holds When someone is removed, move their content to. Set that before you leave Aligned - see 2.3 below.

2.2 Managing your API token

How to generate a new API token

Generate a new API token when nobody copied the original, when the original was lost, or when your security policy requires rotation.

Navigate to Settings → Admin Center → Integrations → Security & Privacy → User provisioning (SCIM).
Click Enable to reopen the connection window.
Click Generate new token.
Read the confirmation and click Generate new token again to confirm.
Click Copy next to the new API token.
Paste the new API token into your identity provider and save.

The previous API token stops working the moment you generate a new one, and user provisioning pauses until you paste the new token into your identity provider. Generating a new token never removes anyone: accounts Aligned already created stay exactly as they are.

2.3 How to choose who gets a leaver's content

Choosing who gets a leaver's content means picking one person to receive everything a removed user owned. Aligned fills this field with the Account Owner by default. Wire and invoice accounts have no Owner, so Aligned picks one of the account Admins instead. You can change it to any other user on your account.

Locate When someone is removed, move their content to in the Connect your identity provider window.
Click the field to open the dropdown, then select any user who already has an Aligned account.
Click Done.

You can only choose someone who already has an Aligned account. This field does not create new users.

Set this before you assign any groups. The person you choose gets the leaver's rooms, room templates, tab templates, Library content, and shared files.

2.4 How to connect your identity provider

Connecting your identity provider means pasting both values into its provisioning settings and switching on the two operations Aligned supports.

Aligned works with any provider that supports SCIM 2.0. The steps below cover Okta. Using a different provider? The SCIM connector base URL and the API token are all it needs - contact support and we will help you set it up.

Okta

Open your Aligned application in Okta.
Navigate to Provisioning → Configure API Integration.
Tick Enable API integration.
Paste the SCIM connector base URL.
Paste the API token.
Click Test API Credentials.
Click Save.
Navigate to Provisioning → To App → Edit.
Tick Create Users.
Tick Deactivate Users.
Keep Update User Attributes OFF - it is not supported.
Click Save.

2.5 How to map roles to your groups

Mapping roles tells Aligned which permission level to give each user. Aligned accepts three values: ADMIN, MANAGER, and USER. You set the value on each group assignment, and Aligned applies it when it creates the account. If you add more than one rule, Aligned uses the highest one.

Navigate to Directory → Profile Editor and select your Aligned application.
Click Add Attribute.
Set Data type to string array.
Set Variable name to roles.
Set External name to roles.
Set External namespace to urn:ietf:params:scim:schemas:core:2.0:User.
Click Save.
Navigate to Provisioning → To App → Attribute Mappings and leave roles unmapped from the Okta user profile.
Navigate to Assignments.
Assign each group and set its roles value.

Set the roles value on each group assignment rather than as an application-level default. An application-level default continues to display Not mapped, which is expected. When someone belongs to two groups with different values, Aligned applies the higher role: Admin outranks Manager, and Manager outranks User.

Send any value other than ADMIN, MANAGER, or USER and Aligned creates the person as a regular User. An unrecognized value never blocks account creation, and Aligned logs the exact value your identity provider sent so support can see it.

2.6 How to confirm provisioning is working

Confirming that provisioning works means checking the Members list in Aligned after you assign a group.

Assign a group in your identity provider.
Navigate to Settings → Admin Center → Members in Aligned.
Confirm the assigned people appear with the role you mapped.

Note:

On credit card accounts, Aligned creates new people as Invite Sent and moves them to Active after they sign in.
On wire and invoice accounts, Aligned does the same while you still have free seats. Once the free seats run out, the extra people are created as Pending.

3. Limitations

User Provisioning (SCIM) does not support the following:

Ongoing role changes. Aligned applies roles at creation only. Moving someone to a different group later leaves their Aligned role unchanged.
Profile syncing in either direction. Change a name in Aligned and Aligned does not send it to your identity provider. Change a name in your identity provider and Aligned does not apply it.
Group import. Aligned receives the role your identity provider decided and does not recreate your group structure.
Setting the Account Owner. The Owner role ties to billing, and only Aligned can change it.
More than one API token per account. Aligned issues one token.
Pulling users. Aligned accepts pushes only. Running Import Users in your identity provider returns nothing, which is expected and does not indicate a broken connection.
Applying roles to people who already exist. Turning User Provisioning on leaves current Aligned accounts untouched and applies roles to newly created people only.

4. Troubleshooting & FAQ

4.1 Expected errors and blocks

Permission restriction
- What this means: Enabling User Provisioning (SCIM) requires Admin access in Aligned.
- How to fix it: Ask an Aligned Admin to complete the setup.
- How to avoid it: Check your role in Settings → Members before you start.
Credential test fails in your identity provider
- What this means: The values in your identity provider do not match the values Aligned issued, or the base URL carries a trailing slash.
- How to fix it: Check both values against the ones Aligned issued, and remove any trailing slash from the SCIM connector base URL. Only if the API token was never copied or has been lost, generate a new one in Aligned and paste it in again.
- How to avoid it: Paste both values in one sitting, immediately after you copy the API token.
Credential test passes but Aligned creates nobody
- What this means: Create Users is unticked in your identity provider, or nobody is assigned to the Aligned application.
- How to fix it: Navigate to Provisioning → To App → Edit, tick Create Users, click Save, then confirm the person appears under Assignments.
Removing someone in your identity provider changes nothing in Aligned
- What this means: Deactivate Users is unticked, so your identity provider never told Aligned to remove them.
- How to fix it: Navigate to Provisioning → To App → Edit, tick Deactivate Users, and click Save. Check your identity provider's system log - in Okta, no application.provision.user.deactivate event means the removal never reached Aligned.
Everyone arrives as a regular User
- What this means: The roles value is unset on the group assignment, or the value your identity provider sent is not ADMIN, MANAGER, or USER.
- How to fix it: Navigate to Assignments, open each group assignment, and set the roles value to one of the three accepted values.
The API token shows no Copy button
- What this means: That token has already been copied, or the page was refreshed before anyone copied it. Each token can be copied once, and Aligned never shows the same value a second time.
- How to fix it: Click Generate new token. Aligned issues a fresh token with its own Copy button - copy that one and paste it into your identity provider. The previous token stops working straight away.
- How to avoid it: Copy the token and paste it into your identity provider in one sitting, before you refresh or leave the page.
Provisioning worked for weeks and then stopped
- What this means: Someone generated a new API token in Aligned and never pasted the new value into the identity provider. The old token stops working the moment a new one is created.
- How to fix it: Check whether a new token was generated in Settings → Admin Center → Integrations → Security & Privacy, then paste the current token into your identity provider again. If the token has not changed, contact Aligned support with your account name, the time the last account was created, and the matching entries from your identity provider's system log.
- How to avoid it: Only generate a new token when you are ready to paste it straight into your identity provider.
Nothing happens after you assign a large group
- What this means: A first-time sync sends every assigned person at once and can take a few minutes to finish.
- How to fix it: Wait a few minutes and check Settings → Admin Center → Members again. If people are still missing, contact Aligned support with your account name, the group you assigned, and the number of people in it.

4.2 FAQ

Q: Does adding a user through User Provisioning cost money?

As long as you have free seats, User Provisioning uses them and nothing is charged. The difference shows once the free seats run out. On credit card accounts Aligned adds a seat and bills for it immediately - assign a group of forty people into ten free seats and thirty new seats are bought. On wire and invoice accounts Aligned creates the extra people as Pending instead, and charges nothing until the seats are arranged.

Q: What happens when I remove a person in my identity provider?

Aligned cuts their access immediately, moves their rooms, templates, Library content and shared files to the person you chose, and frees their seat. Links your clients already hold keep working throughout.

Q: Can I suspend someone in Aligned instead of removing them?

Aligned has no suspended state, so removing someone in your identity provider removes them in Aligned.

Q: What happens if someone leaves and comes back?

Restore them within 30 days and they keep their own settings and profile, so they skip onboarding. Their rooms, templates and content stay with the person who got them, and Aligned does not give them back automatically.

Q: Can I change someone's role in Aligned after Aligned created their account?

You can change a role directly in Aligned, and a later sync from your identity provider never overwrites it.

Q: Which details does Aligned read from my identity provider?

Aligned reads the person's full name and email address, and no other profile fields.

Q: Can I copy the API token more than once?

No. Each token can be copied once. After you copy it the button changes to Generate new token, and refreshing the page without copying loses the value as well. Generating a new token gives you a fresh value with its own Copy button, which you then paste into your identity provider.

Q: Does my identity provider show an error when Aligned cannot create a person?

Your identity provider receives no failure signal from Aligned. Check Settings → Admin Center → Members in Aligned to see which users Aligned created and in which status.

4.3 Security & Data Handling

Aligned stores the API token in a secured form. Once you copy it or refresh the page, Aligned cannot show the value again.
Aligned never writes back to your identity provider.
Aligned retains a removed person's account record for 30 days, then removes it permanently.

4.4 Pro Tips

Tick Create Users and Deactivate Users together during the first setup. Ticking only one leaves provisioning half working, and nothing in Aligned tells you which half is missing.
When someone does not appear in Aligned, check your identity provider's system log before contacting support. It shows whether the request ever left your provider, which is usually the answer.
Assign one small group first and check Settings → Admin Center → Members before you assign the rest of the organization. On credit card accounts, once your free seats run out Aligned buys and bills the extra seats immediately.