Skip to content

SCIM 2.0 API

SCIM (System for Cross-domain Identity Management) is an open standard for automating user provisioning. This API enables integration with identity providers like Microsoft Entra ID (Azure AD), Okta, and other SCIM-compatible systems.

Overview

Use this API to:

  • Automatically provision user accounts from your identity provider
  • Keep user profiles synchronized with your directory
  • Deprovision users when they leave the organization
  • Sync organizational attributes like department and cost center

Configuration

Base URL

All SCIM requests should be made to:

https://{agency-domain}/api/v2/scim

Note: Replace {agency-domain} with your travel agency's domain.

Authentication

The API supports two authentication methods:

Bearer Token (Recommended)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key Header (Alternative)

X-HR-Feed-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The token is the same as used for the HR Feed API. Contact your travel agency administrator to obtain credentials.

API Documentation

Full interactive API documentation is available at:

https://{agency-domain}/api/v2/docs/api-docs#/SCIM

Supported Attributes

This section describes all user attributes supported by the SCIM API.

Core User Attributes

These are standard SCIM 2.0 core user attributes.
Attribute Type Required Description
userName string Yes Unique identifier, typically email
name.givenName string Yes First name
name.familyName string Yes Last name
name.middleName string No Middle name
displayName string No Display name
emails[].value string Yes Email address
emails[].primary boolean No Whether this is the primary email
phoneNumbers[].value string No Phone number
phoneNumbers[].type string No Phone type (e.g., mobile)
active boolean No Whether the user account is active
externalId string No External identifier from identity provider

Enterprise Extension (Cost Fields)

Schema: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

These attributes are mapped to the company's configured cost fields. The mapping depends on your company's cost field configuration.
Attribute Type Description
employeeNumber string Employee ID number
costCenter string Cost center code
organization string Organization/project code
division string Division code
department string Department name

CityCity Extension (Gender + User Group)

Schema: urn:ietf:params:scim:schemas:extension:citycity:2.0:User

The platform requires a user's gender/title to be known for flight bookings and also supports mapping an internal user group through this custom extension. Since these are not supported natively in SCIM core, we use this extension.

If you are using Azure you will need to map fields (such as extensionAttribute1 for gender and extensionAttribute2 for user group). Note that the sync will work without gender, but gender will then have to be assigned by your travel agency or administrator.

If userGroup is provided, it replaces the user's entire internal groups array with that single group value.
Attribute Type Description
gender string Title/salutation: Mr, Ms, or Mrs (case-insensitive, defaults to Mr)
userGroup string Internal user group. If provided, replaces the user's full internal groups array with this single value

User Object

The API returns user objects in SCIM format:

{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:extension:citycity:2.0:User" ], "id": "ABC123", "externalId": "EMP-12345", "userName": "anna.andersson@example.com", "name": { "givenName": "Anna", "familyName": "Andersson", "middleName": "Maria" }, "displayName": "Anna Andersson", "emails": [ { "value": "anna.andersson@example.com", "primary": true } ], "phoneNumbers": [ { "value": "+46701234567", "type": "mobile" } ], "active": true, "meta": { "resourceType": "User", "location": "https://example.com/scim/Users/ABC123" }, "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "department": "Sales", "employeeNumber": "12345" }, "urn:ietf:params:scim:schemas:extension:citycity:2.0:User": { "gender": "Ms", "userGroup": "Sales Managers" } }

Error Responses

Errors are returned in SCIM format:

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "400", "scimType": "invalidValue", "detail": "Description of the error" }
Status Description
400 Bad request (missing required fields, invalid data)
403 Authentication failed or not authorized
404 User not found
409 Conflict (e.g., duplicate user)
500 Internal server error

Azure AD / Microsoft Entra ID Setup

To configure SCIM provisioning in Microsoft Entra ID:

  1. Go to Enterprise Applications → New Application → Create your own application
  2. Select Integrate any other application you don't find in the gallery
  3. Go to Provisioning → Get started
  4. Set Provisioning Mode to Automatic
  5. Enter the Tenant URL: https://{agency-domain}/api/v2/scim
  6. Enter the Secret Token: Your HR Feed API token
  7. Click Test Connection to verify
  8. Configure attribute mappings as needed
  9. Turn off groups syncing ("Provision Microsoft Entra ID Groups"), as this is not supported.
  10. Set Provisioning Status to On

Support

For API access, credentials, or technical support, contact your travel agency administrator.