How to connect to SAP SuccessFactors

SAP SuccessFactors does not use a one-click authorization screen. Instead, an administrator registers an OAuth Client Application with an X.509 certificate inside your own SuccessFactors instance, and then enters five values in Vault. Apideck uses those values to sign a SAML assertion and mint access tokens on your behalf (OAuth2 SAML2-Bearer Assertion), so once the connection is saved the only thing left to renew by hand is the X.509 certificate before it expires.

Before you start

You will need:

• An administrator account in the SuccessFactors instance you want to connect, with Admin Center access sufficient to reach and use the Manage OAuth2 Client Applications screen. If you cannot open that screen, your SuccessFactors administrator can grant the necessary permissions via Admin Center > Manage Permission Roles.
• A decision about which SuccessFactors user the connection will run as, and that user's SuccessFactors userId before you register the client — you enter it during registration (step 2) and again in Vault (step 4). Points worth weighing:
  • Every API call runs with that user's SuccessFactors permissions, so the user needs OData read access to the entities you plan to sync, and write access if your integration creates or updates records.
  • A dedicated API/service user is usually a better choice than a named individual's account, which may be deactivated when that person leaves.
  • The value you need is the SuccessFactors-internal userId, not a username or email address. Admin Center > Integration Center is the authoritative place to look it up (step 3).
• OData API access enabled on that instance, for the module you intend to sync: Employee Central for HRIS data, Recruiting for ATS data.
• A decision about which instance you are connecting. Each SuccessFactors instance — test and production — has its own API server, Company ID, and OAuth client. Credentials are not interchangeable between them, so plan on running this procedure once per instance.
• A tool to generate an X.509 key pair (for example OpenSSL), or the certificate generator built into the SuccessFactors API Center. See step 1.

1. Generate an X.509 key pair

Apideck signs the SAML assertion with the private key, so you must end up holding the private key yourself — it is one of the five values you paste into Vault.

Recommended: generate the key pair with your own tooling, then upload only the public certificate to SuccessFactors in step 2. Apideck recommends this route because the private key then never transits the SuccessFactors UI.

Alternative: generate the certificate inside the registration screen in step 2 (Generate X.509 Certificate) and download the private key when prompted. This is a supported route and it works, but we suggest avoiding it where you can: downloading the private key from the API Center widens its exposure. If you do take this route, download the private key at generation time — you cannot retrieve it later.

Either way, keep the private key .pem file to hand, and note the certificate's expiry date: when the certificate lapses, token requests start failing and the connection stops returning data, so plan to re-register with a fresh certificate before that happens.

Reference: Creating an X.509 Certificate in SAP SuccessFactors.

2. Register a Client Application in SuccessFactors

Everything in this step happens on one form — the certificate and the user binding are both fields on the registration screen, not separate screens to visit afterwards.

1. Sign in to the SuccessFactors instance you are connecting as an administrator.

2. Navigate to Admin Center > API Center > OAuth Configuration for OData. You can also reach the same tool by searching for Manage OAuth2 Client Applications in Action Search.

3. Choose Register Client Application.

4. On the "Register an application" page, fill in:

   • Company — the name of your company.
   • Application Name — a unique name for the OAuth client. Something identifiable such as Apideck makes it easier to find and revoke later.
   • Application URL — a URL describing the client application. This field is only used for 3-legged OAuth, which is not part of this flow, so any valid URL you control is fine.
   • Bind to Users (also labelled Bind to Technical User in some releases) — select this checkbox and enter the userId of the user the connection will run as, the one you decided on in "Before you start". This must be the SuccessFactors-internal userId, not a username or email address — look it up in Admin Center > Integration Center (step 3).
   • X.509 Certificate — paste the public certificate from step 1, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. Alternatively, choose Generate X.509 Certificate here and download the private key.

5. Choose Register to save.

6. Find the new entry in the registered application list and choose View to reveal its API Key. That value is what Vault calls the Client ID.

Why the binding matters: if no user is bound to the client application, interactive business users can still request tokens, but a technical/service user cannot — and a dedicated API/service user is exactly what this guide recommends running the connection as. Binding that user during registration is what makes its token requests succeed. Keep the bound userId and the value you will enter in Username (step 4) identical, character for character.

References: Registering Your OAuth2 Client Application and SAP KBA 2850646 — How to register for OAuth 2.0 authentication.

3. Collect the five values Vault needs

All five come from the same instance you just registered the client in.

Vault field	What to enter	Where to find it
API server	Your instance's API data-center hostname, e.g. apisalesdemo8.successfactors.com	List of SAP SuccessFactors API Servers — match the row for your data center
Company ID	The instance's company identifier	In SuccessFactors, click your profile image (upper right) > Show version information, and read the Company ID value
Username	The userId of the user the connection runs as — the same value you bound to the client application in step 2	Admin Center > Integration Center resolves a user's userId, and is the authoritative route for this value (SAP KBA 3156552). The value in parentheses beside your name in the profile-image panel is the username — it matches the userId on many tenants but is not guaranteed to, so confirm it in Integration Center if authorization fails
Client ID	The API Key from the Client Application you registered in step 2	Admin Center > API Center > OAuth Configuration for OData, then View on your application
Client secret	The full contents of the private key .pem file from step 1, including the -----BEGIN/-----END lines	Your own key file

Two things worth getting right here:

• Username must match the bound userId from step 2. It also determines what Apideck can read — every API call runs with that user's SuccessFactors permissions (see "Before you start").
• API server is a hostname, not a URL. Vault adds the https:// prefix and the trailing slash for you, so enter apisalesdemo8.successfactors.com rather than https://apisalesdemo8.successfactors.com/.

4. Enter the credentials in Vault

1. Open the SAP SuccessFactors connector in Vault and paste in the five values from step 3.
2. Click Save.
3. Click Authorize. Apideck signs a SAML assertion with your private key and exchanges it for an access token against your instance. A successful authorization means the credentials and the user binding are working.

Your SAP SuccessFactors account is now connected.

Notes

• One connection serves both verticals. The same credentials back HRIS (Employee Central) and ATS (Recruiting) data — you do not register separate clients per Unified API. What you actually get back is bounded by which modules are enabled on the instance and by the permissions of the user in the Username field.
• Token handling is automatic. Each time Apideck authenticates or refreshes the connection, it signs a fresh short-lived SAML assertion (valid 10 minutes) and asks SuccessFactors for a genuinely new access token rather than accepting one SuccessFactors may still be holding — so the token in use is always newly issued at that point. That token is then reused for up to 24 hours before Apideck requests the next one. There is no refresh token to store and nothing to rotate on your side apart from the X.509 certificate when it approaches expiry.
• Revoking access is done from your side: delete the registered Client Application in Admin Center > API Center > OAuth Configuration for OData. That immediately stops Apideck from obtaining any new token. SuccessFactors may not invalidate a token Apideck already holds, so assume the connection can keep working for up to 24 hours before it fails on its next token request. If you need access to stop sooner than that, also delete the connection in Vault — that removes the stored credentials and the token along with them.
• Repeat per instance. Connecting your test instance after your production instance (or the reverse) means a second Client Application, a second certificate, and a second Vault connection with that instance's own API server and Company ID.

Troubleshooting

"Unable to generate token. User is not bound to the client application." This is SAP's own error text, and it means exactly what it says: the user in Username is a technical/service user that was not bound to the OAuth client application. Reopen the registration in Admin Center > API Center > OAuth Configuration for OData, select Bind to Users, enter that user's userId, and save (step 2). Note this error only appears for technical/service users — an unbound interactive business user can still obtain tokens, which is why the same client can look fine when tested under an admin's own account and fail for the service user the connection runs as.

"This User ID is not a Technical User ID." On releases where the binding field is labelled Bind to Technical User, it validates that the ID you enter belongs to a technical user, so entering a regular business or named-individual user's ID is rejected with this error (SAP KBA 2895460). Either bind a dedicated technical/API user — the option this guide recommends — or, if the connection must run as a named individual, leave the binding off entirely: an unbound interactive business user can still obtain tokens.

Authorization fails with an invalid grant or 401 error. Work through the five values in order:

• Client ID must be the generated API Key, not the application name you chose.
• Client secret must be the private key, complete with its -----BEGIN/-----END lines and line breaks intact — not the public certificate, and not a truncated copy/paste.
• Username must be the SuccessFactors-internal userId — not an email address, a display name, or the username in the profile-image panel unless Integration Center confirms the two match — and must equal the userId bound to the client application in step 2 exactly.
• Company ID and API server must both belong to the same instance in which the OAuth client was registered. Mixing a test Company ID with a production API server is the most common cause of this failure.

Authorization succeeds but requests return no data. The user in Username most likely lacks OData permissions for that entity. Grant read access for the entities you are syncing and retry.

Requests fail for an entity that exists in your instance. Confirm the relevant module has OData API access enabled — Employee Central for HRIS entities, Recruiting for ATS entities.

The connection worked and then stopped. Check whether the X.509 certificate on the registered Client Application has expired, or whether the user in Username has been deactivated. Both break token minting without any change on the Apideck side.

Still stuck? Contact Apideck Support with the Company ID and API server you used (never the private key) and we can check what the authorization attempt returned.