Skip to main content
Version: 1.0

Roam HQ SCIM 2.0 API

System for Cross-domain Identity Management (SCIM) v2 is a standard protocol for automating user provisioning. Roam HQ supports SCIM 2.0 to allow enterprise identity providers (IdPs) like Okta to seamlessly create, update, deactivate, and synchronize user accounts in Roam.

OpenAPI Spec: scim.json

SCIM Base URL and Authentication​

All SCIM API endpoints are served under the following base URL:

  • Base URL: https://api.ro.am/scim/v2

Access to the SCIM API requires an App configured with the following scopes:

  • user:read, user:read.email - for GET operations
  • user:write - for write operations

In "Roam Administration > Technical Setup", click "Enable SCIM" to automatically generate an App and retrieve its Bearer token. Include the token in the Authorization: Bearer <token> header. Discovery endpoints (/ServiceProviderConfig, /Schemas, /ResourceTypes) do not require authentication.

Supported Endpoints​

Roam exposes standard SCIM endpoints for Users (plus discovery endpoints). All endpoints accept and return data in the SCIM 2.0 JSON format (application/scim+json).

EndpointMethods
/ServiceProviderConfigGET
/ResourceTypesGET
/Schemas, /Schemas/{schemaId}GET
/Users, /Users/{id}GET, POST, PUT, PATCH, DELETE
/Groups, /Groups/{id}GET, POST, PUT, PATCH, DELETE

Note: PATCH is supported with limitations:

  • Users: only replace of active is supported.
  • Groups: add/remove/replace of members, and replace of displayName are supported.

User Schema Highlights​

  • Required: Users minimally require a name and email: userName (email), name.givenName, name.familyName, emails[0].value

  • displayName: Roam constructs the display name from givenName & familyName automatically. Any value you send for displayName will be ignored (no error).

  • userName: Must match the primary email address.

  • Immutable: Email/userName cannot be changed once created.

    If an email must change (e.g., corporate email change), the current workaround is to archive the old user and create a new user with the new email, or contact Roam support for options.

  • Active: active: false archives a user; active: true reactivates.

  • No Password Sync: Roam does not use passwords and does not support SCIM password management. The password attribute in SCIM is ignored and will not be returned.

  • Role Extension: Custom extension urn:ro.am:params:scim:schemas:extension:roam:2.0:User.role accepts User or Admin, defaulting to "User". This role controls access to Roam Administration.

User Schema Reference​

SCIM User Resource – Schema and Behavior

Roam’s SCIM User resource conforms to the SCIM core User schema (urn:ietf:params:scim:schemas:core:2.0:User) with a custom extension for user role. The following attributes are supported or have special behavior in Roam:

  • id: (string, read-only) – The unique identifier for the user in Roam. This is Roam’s internal Person ID, returned as a string in SCIM responses. The id is generated by Roam and cannot be changed by the client.

  • userName: (string, required) – The username for the account. Roam uses the email address as the userName. When creating a user, the userName field must be the user’s email address, and it must exactly match the primary email value provided. If userName does not match the email, the creation is rejected ("userName must match primary email" error). Once a user is created, the userName/email is immutable – any attempt to change a user’s email or userName via SCIM will be rejected with a 400 error ("email may not be updated"). (Uniqueness: Roam enforces that no two users in the same account have the same email/userName; creating a user with an email that already exists in your Roam account returns a SCIM uniqueness error 409.)

  • name: (complex, required) – The structured name of the user. Roam requires both givenName (first name) and familyName (last name) to be provided in the name object when creating or updating a user. If either is missing, the request is rejected ("name must contain givenName and familyName" error). Roam constructs the display name internally from these components. (Middle names or honorifics are not explicitly handled by SCIM in this implementation.)

  • displayName: (string) – The full name of the user, typically for display purposes. Roam ignores any displayName value sent in a SCIM request. Instead, Roam will automatically set the display name to “givenName + familyName” (with a space) on the user’s account. In SCIM GET responses, displayName is always populated with the user’s full name as stored in Roam. (Any displayName provided on create/update is accepted but silently ignored.)

  • emails: (array of complex) – The email addresses for the user. Roam requires at least one email and uses the first entry as the primary email. You should provide an array with a single object containing the user’s email, e.g. emails: [{ "value": "alice@company.com", "primary": true, "type": "work" }]. The primary email’s value must equal the userName (Roam enforces this). Additional email entries (secondary emails) are ignored in the current implementation – only one email (the primary) is stored. The primary email cannot be changed after creation (immutable, as noted above).

  • active: (boolean) – The active status of the user’s account. If omitted on create, Roam assumes active: true (meaning the account is active/enabled). Set active: false to indicate the user should be deactivated in Roam. Deactivation behavior: If active is set to false in a PUT (or if the SCIM Delete operation is called), Roam will mark the user as Archived, which revokes their access but keeps their account record. Setting active: true on an archived user will reactivate (un-archive) them.

  • externalId: (string, optional) – An external identifier for the user, typically used to correlate the Roam user with the IdP’s user record. Roam will store this value (if provided) as an external HR system ID for the user. The externalId is returned in GET responses if it was set. Roam does not enforce uniqueness or format on this field; it’s solely for the client’s reference. (When a user is archived or reprovisioned, the externalId remains stored unless overwritten by a subsequent update.)

  • password: (string, optional) – Not supported. Roam does not use or sync user passwords via SCIM. If a password attribute is included in a request, it will be ignored. Roam does not return a password attribute in any response.

  • Roles (Custom Extension): Roam defines a custom SCIM extension to assign user roles (standard User vs Admin in Roam). The extension URN is: urn:ro.am:params:scim:schemas:extension:roam:2.0:User.

    Under this extension, Roam supports a single attribute: role. This is a string indicating the user’s role in Roam, with allowed values "User" or "Admin". In SCIM responses, each user’s data will include a section like:

        "urn:ro.am:params:scim:schemas:extension:roam:2.0:User": \{
            "role": "User"
        \}

    By default, if you do not supply this extension on create, Roam will assign new users the role "User" (regular non-admin).

Apart from the above, Roam’s SCIM user implementation ignores any other standard SCIM user attributes that are not listed. Attributes such as middleName, honorificPrefix/Suffix, title, phoneNumbers, department, etc., if sent, will be ignored (and logged as unknown) -- they will not be stored or returned. The SCIM schemas list for a User will include both the core User schema URN and Roam’s extension URN (since the role sub-attribute is always present in responses, even if its value is "User" by default).

Okta Integration Steps (Summary)​

  1. In Okta, create a SCIM 2.0 App Integration.
  2. Set Base URL to https://api.ro.am/scim/v2.
  3. Provide a Roam API token with required scopes.
  4. Test connection (Okta hits /ServiceProviderConfig).
  5. Enable Create Users, Update Users, Deactivate Users.
  6. Map attributes: The default mappings should work, but these are the ones required:
    • First Name → name.givenName
    • Last Name → name.familyName
    • Email → userName / emails[primary]
  7. (Optional) Map a custom attribute to the role extension for admin assignment.
  8. Assign users to the app and monitor provisioning logs.

By following the above documentation and guidelines, you should be able to successfully integrate SCIM 2.0 provisioning for your Roam organization. This will automate user management and ensure your Roam user directory stays in sync with your identity provider. For further questions or support, reach out to Roam’s developer support.

Contact

Developer Support: developer@ro.am

URL: https://developer.ro.am

Terms of Service

https://ro.am/terms