Authentication & Security

Security lies at the heart of working with ERPx data. All API requests must be properly authenticated, and every integration must adhere to contemporary identity standards. This section outlines the principles of authentication, advises on the appropriate flows for your use case, and provides guidance on keeping your integrations secure.

Our APIs support:

• OAuth 2.0 for token-based authentication
• Federated authentication with trusted Identity Providers
• Machine-to-Machine authentication for back-end or scheduled integrations

Access tokens confirm who is calling the API. Your application is responsible for enforcing what that caller is permitted to do.    

OAuth 2.0 Authentication

Most ERPx integrations use OAuth 2.0 to:

1. Request an access token from an Identity Provider
2. Send the token as a Bearer token in the Authorization header
3. Use token claims (e.g., roles) to map users in your tenant

Example:

GET /v1/employees/{personId}
Authorization: Bearer <your-access-token>

Note: Tokens establish identity, not permissions. Your application must enforce authorisation rules.    

Federated authentication

With federated identity, a user signs in once with a trusted Identity Provider (IdP) such as Unit4 Identity Services (U4IDS). The Federated Authentication works by following these rules:

• Users never share credentials directly with your application.
• Applications trust the IdP to verify identity.
• Access is granted via tokens, using industry standards. This Federated Authentication approach enables single sign-on (SSO) across ERPx and related systems.

Unit4 Identity Services (U4IDS)

The most common setup uses Unit4 Identity Services (U4IDS) to do the following:

• Implement OpenID Connect, built on OAuth 2.0.
• Issue JWT tokens that are validated by the ERPx API host. Applications obtain tokens from U4IDS endpoints and use them to call ERPx APIs securely.    

Machine-to-Machine authentication

Some integrations do not involve a human user, such as scheduled jobs, back-end connectors. In these cases, you can use the Client Credentials Flow that works by following these rules:

• Your system authenticates directly with the IdP using a client ID and secret.
• The IdP returns an access token tied to a single tenant.
• This ensures a strict data isolation: a client can only access its designated tenant.
• A specific configuration is required in ERPx: a dedicated user account must be established with M2M (Machine-to-Machine) credentials and assigned to either the SUPER or SYSTEM role.

Example

Smart Recruiters Integration built with Extension Kit flows. The authentication works as follow:

• A dedicated client is provisioned per tenant in U4IDS.
• Those credentials are used to authenticate API calls within the flow.    

How to get your ERPx authentication credentials

When a new tenant environment is provisioned, essential credentials and access instructions are distributed through a series of emails. These typically include a “my instance document,” which outlines the environment details for each instance type, such as Production or Non-Production Environments (PREV and ACC).

As part of the onboarding process, an early access account is created, and its details are communicated to the customer. This account enables initial logins to the respective environments.

In addition to user access, specific information is provided separately: the client secret and client ID required for integrating with ERPx APIs. These credentials are necessary for Machine-to-Machine (M2M) authentication and a Unit4 ID is provided for all customer tenants.

Customers may request up to 10 individual M2M client IDs. This allows for separation of credentials across different integrations, thereby minimising risk in case of credential compromise and supporting best practices in credential management.

In summary, receiving and managing your authentication credentials involves:

• Receiving environment details and access information via email upon tenant provisioning.
• Using the supplied early access account to log into each environment.
• Obtaining your unique client ID and secret for ERPx API integrations through a secure, separate communication.
• Requesting up to 10 distinct M2M client IDs to ensure security and integration flexibility.

By following this process, each tenant maintains secure, isolated, and well-managed access to ERPx APIs, supporting both operational needs and security requirements.    

How to use your ERPx credentials

After obtaining your client ID and secret, you should implement the Client Credentials Flow for authentication.

To test API calls using Postman or similar tools, input your client ID, client secret, scope as ‘u4erp’, and set the grant type to client_credentials to generate a bearer token. Use the generated token for authorisation by selecting ‘Bearer Token’ as the authentication type.

For integration purposes, when making an API call, send a token request directly to the Identity Provider (IdP) token endpoint, including your client ID, client secret, and by specifying the scope (U4erp) within the request payload. Upon successful authentication, the IdP will issue an access token unique to your tenant. You should include this token as a bearer token in the Authorisation header of all subsequent API requests.    

Security best practices

• Use HTTPS Exclusively: Ensure all API communications are encrypted during transit.
• Safeguard Credentials: Do not embed client credentials in code or store them in public repositories.
• Plan for Token Expiration: Set up token refresh mechanisms to address downtime; tokens are valid for 3600 seconds.
• Enforce Tenant Isolation: Confirm that tokens are mapped exclusively to the appropriate tenant.    

Next steps

• Follow Getting Started to make your first request.
• Explore the API Reference for endpoints and payloads.
• Review Business use case for real-world scenarios.