Instances

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:

Level	Type	Description
1	Production	Live business data
2	Pre-production	Final testing before go-live
3	Quality	QA and integration testing
4	Development	Developer sandbox
5	Sandbox	Safe 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

Navigate to a System
Click Add Instance
Configure the instance:

Field	Description	Example
Environment	Instance level	Development
Base URL	SAP OData endpoint	`https://my-s4.s4hana.cloud.sap`
Alias	Optional override	`dev-eu`
Description	Optional 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

Type	Description
Basic	Username and password
OAuth 2.0	Client credentials flow
API Key	Custom header authentication
Custom Headers	Any custom headers
None	No authentication (public APIs)

Configuring Authentication

Go to the instance settings
Click Configure Authentication
Select the authentication type
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:

Instance Level: Specific to one environment
System Service Level: Shared across instances for a service
Instance Default: Fallback for the instance

The platform uses the most specific configuration available.

Managing Instances

Edit Instance

Navigate to the instance
Update fields as needed
Click Save

Delete Instance

Deleting an instance removes all service bindings and breaks any API keys that only have access to this instance.

Navigate to the instance
Click Delete Instance
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:

Status	Description
Healthy	Connection successful
Degraded	Slow response times
Unavailable	Cannot connect
Unknown	Not 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:

Create new credentials in SAP
Update the instance configuration
Verify connectivity
Disable old credentials in SAP

Testing New Instances

Before using a new instance:

Configure authentication
Click Test Connection
Bind at least one service
Test with a simple API call

// Quick connectivity test
const test = await client.A_BusinessPartner.list({
  connection: 'new-instance',
  top: 1
});

Getting Started

SDK

Platform

Concepts

Overview

Instance Types

Instance Priority

Creating an Instance

Via Dashboard

Base URL Format

Authentication

Authentication Types

Configuring Authentication

Authentication Inheritance

Managing Instances

Edit Instance

Delete Instance

Connection String

Health Monitoring

Best Practices

URL Consistency

Credential Rotation

Testing New Instances

​Overview

​Instance Types

​Instance Priority

​Creating an Instance

​Via Dashboard

​Base URL Format

​Authentication

​Authentication Types

​Configuring Authentication

​Authentication Inheritance

​Managing Instances

​Edit Instance

​Delete Instance

​Connection String

​Health Monitoring

​Best Practices

​URL Consistency

​Credential Rotation

​Testing New Instances

Overview

Instance Types

Instance Priority

Creating an Instance

Via Dashboard

Base URL Format

Authentication

Authentication Types

Configuring Authentication

Authentication Inheritance

Managing Instances

Edit Instance

Delete Instance

Connection String

Health Monitoring

Best Practices

URL Consistency

Credential Rotation

Testing New Instances