> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAP SuccessFactors

> Connect Serval to SAP SuccessFactors to read and write HR data - users, employment records, org structure, time off, performance, recruiting, and onboarding - from workflows.

## About SAP SuccessFactors

SAP SuccessFactors is SAP's cloud HCM suite - core HR (Employee Central), performance and goals, recruiting, onboarding, and time management. Serval connects to one SuccessFactors tenant per connection - the connection is named "SAP SuccessFactors \[Company ID]" - and calls the tenant's OData V2 APIs on demand when your workflows run.

**Authentication:** OAuth 2.0 with SAML 2.0 bearer assertions - the only method SAP supports for new integrations (HTTP Basic Auth retires in November 2026). Serval signs a short-lived SAML assertion with a private key whose X.509 certificate is registered on an OAuth client in your tenant, exchanges it for a bearer token, and refreshes automatically. Serval can generate the key pair for you, so the private key never leaves Serval and you only ever handle the public certificate - SAP's recommended setup.

**Data sync:** On demand only. SuccessFactors data is read or written when a workflow step runs - there is no background sync or entity ingestion.

## What the SuccessFactors integration enables

| Capability               | Description                                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Users and employee data  | Read and update user accounts, personal information, and employment records (User, PerPerson, EmpJob, and related entities).    |
| Organization structure   | Read Foundation Objects - departments, divisions, locations, cost centers.                                                      |
| Time off                 | Read and manage absences, balances, and time types (Employee Central Time Off).                                                 |
| Performance and goals    | Goal plans, continuous performance activities, review forms, feedback, and 360 reviews.                                         |
| Recruiting               | Candidates, job requisitions, applications, offers, and interviews.                                                             |
| Onboarding               | Current-generation Onboarding (OBX) processes and tasks.                                                                        |
| Connection health checks | Built-in checks verify authentication, user listing, and - where Employee Central is licensed - person and org-structure reads. |

Serval exposes one typed API request action per module, all calling the tenant's `/odata/v2` root. Entities from modules your tenant doesn't license return permission errors - that's expected and doesn't indicate a broken connection.

## Permissions model

SuccessFactors OAuth tokens carry no scopes. What a connection can access is controlled entirely by the **role-based permissions (RBP)** of the API user you name in the connection. Create a dedicated API user and grant it a permission role with exactly the OData entity access your workflows need.

## Before you start

You need:

* Admin access to your SuccessFactors tenant with the **Manage Integration Tools → Manage OAuth2 Client Applications** permission.
* Your tenant's **API server** and **company ID**. Both are visible to admins in **Admin Center → API Center**; the company ID is also shown in the upper-right corner of Admin Center. The API server is data-center specific (for example `api4.successfactors.com`) - if you're unsure, ask whoever administers your tenant, or see SAP's [List of SAP SuccessFactors API Servers](https://help.sap.com/docs/successfactors-platform/sap-successfactors-api-reference-guide-odata-v2/list-of-sap-successfactors-api-servers).

## Step 1 - Create a dedicated API user

<Steps>
  <Step title="Create the user">
    Create a user such as `sfapi.serval`. A dedicated user keeps the connection's access auditable and independent of any employee's account.
  </Step>

  <Step title="Grant it a permission role">
    In **Admin Center → Manage Permission Roles**, create a role for the integration and assign it to the API user (via a permission group). Grant the OData API access your workflows need - typically **User Search** under General User Permission, plus the **Employee Central API** permissions (effective-dated entities) if you use Employee Central, and module permissions for anything else your workflows touch (Recruiting, Time Off, and so on).
  </Step>
</Steps>

<Note>
  Grant the minimum entity access your workflows need. The API user's role is the connection's entire authorization surface - there are no OAuth scopes to narrow it further.
</Note>

## Step 2 - Register the OAuth client and connect

In Serval, open the SAP SuccessFactors integration and choose **Connect**. Fill in the API server and company ID, then:

<Tabs>
  <Tab title="Generate a certificate in Serval (recommended)">
    <Steps>
      <Step title="Generate the certificate">
        With **Certificate** set to "Generate a certificate for me", choose **Generate certificate**. Serval creates the key pair, shows the public certificate, and keeps the private key - it is never displayed and never leaves Serval.
      </Step>

      <Step title="Register the client application in SuccessFactors">
        In **Admin Center → API Center → OAuth Configuration for OData**, choose **Register Client Application**. Enter an application name (for example "Serval") and application URL (identification only), and paste the certificate from Serval into the **X.509 Certificate** field. Save the registration.
      </Step>

      <Step title="Copy the API key back to Serval">
        Choose **View** on the registered application and copy its **API key** into Serval's **Client ID (API key)** field.
      </Step>

      <Step title="Enter the API user and submit">
        Enter the API user ID from step 1 and submit. Serval runs health checks automatically.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Use your own certificate (own PKI)">
    <Steps>
      <Step title="Register your certificate in SuccessFactors">
        Register a client application as above, pasting your certificate's base64 body into the **X.509 Certificate** field - enter only the body, without the BEGIN and END lines, or SuccessFactors rejects it.
      </Step>

      <Step title="Connect with the matching private key">
        In Serval, set **Certificate** to "Paste my own private key" and paste the RSA private key that matches the registered certificate, including the BEGIN and END lines. Copy the application's **API key** into the Client ID field, enter the API user ID, and submit.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  Consider enabling <b>Bind to Users</b> on the OAuth client and binding it to your API user, so only that user can request tokens for this client. Also note: changing or regenerating the certificate on a registered client invalidates the existing configuration - rotate by updating both sides together.
</Note>

## Troubleshooting

| Symptom                                            | Likely cause                                                                                                                                                            |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Health check fails with a 401 or invalid\_grant    | The certificate registered on the OAuth client doesn't match the private key, or the client ID / company ID / API user ID doesn't match the tenant.                     |
| Worked before, now 401s                            | The certificate was regenerated or replaced on one side only - re-register the current certificate, or generate a new one in Serval and update the client registration. |
| User reads work but Employee Central entities fail | The tenant doesn't use Employee Central, or the API user's role lacks Employee Central OData permissions.                                                               |
| A module's endpoints return 403 or "no permission" | The module isn't licensed on the tenant, or the API user's role-based permissions don't cover those entities.                                                           |