Skip to main content

​
Overview

Instances represent specific SAP environments within a system. Each instance has its own base URL and can have its own authentication configuration.

​
Instance Types

S4Kit supports five instance levels, in priority order:
LevelTypeDescription
1ProductionLive business data
2Pre-productionFinal testing before go-live
3QualityQA and integration testing
4DevelopmentDeveloper sandbox
5SandboxSafe testing environment

​
Instance Priority

When an API key has access to multiple instances and no specific instance is requested, S4Kit automatically selects the highest-priority available instance. 
// If API key has access to dev and sandbox, dev is used
const partners = await client.A_BusinessPartner.list();

// Override to use a specific instance
const sandboxPartners = await client.A_BusinessPartner.list({
  connection: 'sandbox'
});

​
Creating an Instance

​
Via Dashboard

  1. Navigate to a System
  2. Click Add Instance
  3. Configure the instance:
FieldDescriptionExample
EnvironmentInstance levelDevelopment
Base URLSAP OData endpointhttps://my-s4.s4hana.cloud.sap
AliasOptional overridedev-eu
DescriptionOptional notes”EU development server”

​
Base URL Format

The base URL should point to your SAP gateway: 
# S/4HANA Cloud
https://my123456.s4hana.cloud.sap

# On-Premise
https://sap-gateway.company.com:8443

# SAP BTP
https://my-service.cfapps.eu10.hana.ondemand.com
Don’t include the OData service path in the base URL. The platform appends the service path automatically.

​
Authentication

Each instance can have its own authentication configuration, or inherit from the system level.

​
Authentication Types

TypeDescription
BasicUsername and password
OAuth 2.0Client credentials flow
API KeyCustom header authentication
Custom HeadersAny custom headers
NoneNo authentication (public APIs)

​
Configuring Authentication

  1. Go to the instance settings
  2. Click Configure Authentication
  3. Select the authentication type
  4. Enter credentials
Credentials are encrypted before storage. They cannot be viewed after saving—only updated or removed.

​
Authentication Inheritance

Authentication can be configured at multiple levels:
  1. Instance Level: Specific to one environment
  2. System Service Level: Shared across instances for a service
  3. Instance Default: Fallback for the instance
The platform uses the most specific configuration available.

​
Managing Instances

​
Edit Instance

  1. Navigate to the instance
  2. Update fields as needed
  3. Click Save

​
Delete Instance

Deleting an instance removes all service bindings and breaks any API keys that only have access to this instance.
  1. Navigate to the instance
  2. Click Delete Instance
  3. Confirm the deletion

​
Connection String

Each instance has a connection string for the SDK: 
// Using system alias (uses highest-priority instance)
const client = new S4Kit({
  apiKey: 'sk_live_...',
  connection: 'production'
});

// Using specific instance alias
const devClient = new S4Kit({
  apiKey: 'sk_live_...',
  connection: 'dev'
});

​
Health Monitoring

The dashboard shows instance health status:
StatusDescription
HealthyConnection successful
DegradedSlow response times
UnavailableCannot connect
UnknownNot yet tested
Click Test Connection to verify an instance is reachable.

​
Best Practices

​
URL Consistency

Keep base URLs consistent across environments: 
Production:  https://prod.s4hana.cloud.sap
Quality:     https://qa.s4hana.cloud.sap
Development: https://dev.s4hana.cloud.sap

​
Credential Rotation

Regularly rotate SAP credentials:
  1. Create new credentials in SAP
  2. Update the instance configuration
  3. Verify connectivity
  4. Disable old credentials in SAP

​
Testing New Instances

Before using a new instance:
  1. Configure authentication
  2. Click Test Connection
  3. Bind at least one service
  4. Test with a simple API call
// Quick connectivity test
const test = await client.A_BusinessPartner.list({
  connection: 'new-instance',
  top: 1
});