Principal ID

Last updated: September 23, 2026

The Principal ID is the identifier by which a Contact is known in systems connected to Eduframe, such as Canvas LMS, Brightspace LMS and Single Sign-On (SSO). This article explains how to use the Principal ID in the Eduframe API, where Admins find and change it, and what the Manage externally setting does.

What is a Principal ID?

The Principal ID is a text value that uniquely identifies a Contact within your Eduframe environment. Every Contact has a Principal ID, including Participants, Teachers and Admins. By default, the Principal ID is the Contact's Eduframe ID. As an Admin, you can replace it with your own value, for example the ID the Contact has in your Student Information System (SIS).

Eduframe uses the Principal ID in the following places:

  • Canvas LMS (Learning Management System): The SIS User ID and SIS Login ID of the Canvas user that Eduframe creates for the Contact.

  • Brightspace LMS: The OrgDefinedId of the Brightspace user that Eduframe creates for the Contact.

  • Single Sign-On (SSO): The user identifier that Eduframe sends to a connected system when the Contact logs in through Eduframe.

  • Eduframe API: The principal_id in the Contact's external_identity. API users can look up a Contact by Principal ID instead of by Eduframe ID.

How can I use the Principal ID in the Eduframe API?

The Eduframe API exposes the Principal ID on Contacts (users):

  • A Contact contains an external_identity object with the principal_id and managed_externally values.

  • To request a Contact by Principal ID, prefix the identifier in the URL with principal_id:, for example /api/v1/users/principal_id:4821. Without the prefix, Eduframe treats the value as the Eduframe ID.

  • To create a Contact with a Principal ID, include an external_identity with principal_id and managed_externally.

  • To change the Principal ID or the Manage externally setting of an existing Contact, use POST /api/v1/users/{id}/external_identity.

Find out more about the exact requests and responses in the Eduframe API documentation.

How can I find and change the Principal ID of a Contact?

As an Admin, open the Contact. The Principal ID is shown at the top of the Contact form. To change it, click Edit (pencil icon) next to it, enter the new value and click Save..

Note: Changing a Principal ID can affect connected systems such as your LMS, and might be hard to reverse. Check the new value before you click Save.

How can I set the Principal ID when creating a Contact?

When an Admin creates a new Contact, the form contains a Principal ID field and a Manage externally checkbox.

  • Enter a value in Principal ID to use your own identifier.

  • Leave Principal ID empty to use the Contact's Eduframe ID.

Participants cannot set their own Principal ID when they enroll through a Registration Form. As an Admin, set the Principal ID afterwards on the Contact.

What does Manage externally mean?

Manage externally is a setting on a Contact that tells Eduframe that another system manages the Contact's user account. When Manage externally is enabled, Eduframe no longer creates or updates the Contact's user account and logins in the connected LMS. Use this setting for users that your own identity provider or SIS already creates in the LMS.

Tip: When you enable Manage externally, make sure the Principal ID in Eduframe is equal to the ID of the user in the connected system. Eduframe uses the Principal ID to find the user there.

What happens to the Principal ID when I merge two Contacts?

When an Admin merges duplicate Contacts, the primary Contact keeps its Principal ID. The Principal ID of the other Contact is not kept. Find out more on 📄 How to Merge Duplicate Contacts?

What if I see "Principal ID has already been taken"?

Each Principal ID can be used only once within your Eduframe environment. Eduframe does not distinguish uppercase and lowercase letters, so ABC123 and abc123 count as the same Principal ID. If you see the "Principal ID has already been taken" message:

  1. Search Contacts for the Principal ID you entered.

  2. If the other Contact is a duplicate, merge the two Contacts.

  3. If the other Contact is a different person, enter a different Principal ID.

Related articles