Destination Service REST API - Complete Reference

Source: https://github.com/SAP-docs/btp-connectivity/blob/main/docs/1-connectivity-documentation/destination-service-rest-api-23ccafb.md

API Specification: https://api.sap.com/api/SAP_CP_CF_Connectivity_Destination

Overview

The Destination Service REST API enables programmatic management of destinations, certificates, and destination fragments on SAP BTP.

Authentication

Get OAuth Access Token

# Extract credentials from service key
clientId="<from-service-key>"
clientSecret="<from-service-key>"
tokenUrl="<from-service-key>/oauth/token"
destinationUri="<from-service-key>"

# Request access token
curl -X POST "${tokenUrl}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  --data-urlencode "client_id=${clientId}" \
  --data-urlencode "client_secret=${clientSecret}"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "uaa.resource"
}

Using mTLS (Recommended)

For enhanced security, use X.509 certificates instead of client secrets:

curl -X POST "${tokenUrl}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --cert client-cert.pem \
  --key client-key.pem \
  -d "grant_type=client_credentials" \
  --data-urlencode "client_id=${clientId}"

Base URL

{destinationUri}/destination-configuration/v1

The destinationUri is obtained from the service key (field: uri).

Endpoints

Subaccount Destinations

List All Destinations

GET /subaccountDestinations

curl -X GET "${destinationUri}/destination-configuration/v1/subaccountDestinations" \
  -H "Authorization: Bearer ${access_token}"

Response:

[
  {
    "Name": "my-destination",
    "Type": "HTTP",
    "URL": "https://api.example.com",
    "Authentication": "OAuth2ClientCredentials",
    "ProxyType": "Internet"
  }
]

Get Specific Destination

GET /subaccountDestinations/{destinationName}

curl -X GET "${destinationUri}/destination-configuration/v1/subaccountDestinations/my-destination" \
  -H "Authorization: Bearer ${access_token}"

Create Destination

POST /subaccountDestinations

curl -X POST "${destinationUri}/destination-configuration/v1/subaccountDestinations" \
  -H "Authorization: Bearer ${access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "new-destination",
    "Type": "HTTP",
    "URL": "https://api.example.com",
    "Authentication": "BasicAuthentication",
    "ProxyType": "Internet",
    "User": "username",
    "Password": "password"
  }'

Update Destination

PUT /subaccountDestinations/{destinationName}

curl -X PUT "${destinationUri}/destination-configuration/v1/subaccountDestinations/my-destination" \
  -H "Authorization: Bearer ${access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "my-destination",
    "Type": "HTTP",
    "URL": "https://api.updated.example.com",
    "Authentication": "BasicAuthentication",
    "ProxyType": "Internet",
    "User": "newuser",
    "Password": "newpassword"
  }'

Delete Destination

DELETE /subaccountDestinations/{destinationName}

curl -X DELETE "${destinationUri}/destination-configuration/v1/subaccountDestinations/my-destination" \
  -H "Authorization: Bearer ${access_token}"

Service Instance Destinations

List Instance Destinations

GET /instanceDestinations

curl -X GET "${destinationUri}/destination-configuration/v1/instanceDestinations" \
  -H "Authorization: Bearer ${access_token}"

CRUD Operations

Same as subaccount destinations but using /instanceDestinations path.

Find Destination (with Authentication)

The most commonly used endpoint - retrieves destination configuration with authentication tokens.

GET /destinations/{destinationName}

curl -X GET "${destinationUri}/destination-configuration/v1/destinations/my-destination" \
  -H "Authorization: Bearer ${access_token}"

Response Structure:

{
  "owner": {
    "SubaccountId": "abc123",
    "InstanceId": null
  },
  "destinationConfiguration": {
    "Name": "my-destination",
    "Type": "HTTP",
    "URL": "https://api.example.com",
    "Authentication": "OAuth2ClientCredentials",
    "ProxyType": "Internet",
    "clientId": "...",
    "tokenServiceURL": "..."
  },
  "authTokens": [
    {
      "type": "Bearer",
      "value": "eyJhbGciOiJSUzI1NiIs...",
      "http_header": {
        "key": "Authorization",
        "value": "Bearer eyJhbGciOiJSUzI1NiIs..."
      },
      "expires_in": "43199",
      "scope": "read write"
    }
  ],
  "certificates": []
}

With User Token (Principal Propagation)

For destinations requiring user context:

curl -X GET "${destinationUri}/destination-configuration/v1/destinations/my-destination" \
  -H "Authorization: Bearer ${access_token}" \
  -H "X-user-token: ${user_jwt}"

With Destination Fragment

curl -X GET "${destinationUri}/destination-configuration/v1/destinations/my-destination" \
  -H "Authorization: Bearer ${access_token}" \
  -H "X-Fragment-Name: my-fragment"

Certificates

List Certificates

GET /subaccountCertificates

curl -X GET "${destinationUri}/destination-configuration/v1/subaccountCertificates" \
  -H "Authorization: Bearer ${access_token}"

Upload Certificate

POST /subaccountCertificates

curl -X POST "${destinationUri}/destination-configuration/v1/subaccountCertificates" \
  -H "Authorization: Bearer ${access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "my-certificate",
    "Type": "CERTIFICATE",
    "Content": "base64-encoded-certificate"
  }'

Delete Certificate

DELETE /subaccountCertificates/{certificateName}

curl -X DELETE "${destinationUri}/destination-configuration/v1/subaccountCertificates/my-certificate" \
  -H "Authorization: Bearer ${access_token}"

Destination Fragments

List Fragments

GET /subaccountDestinationFragments

curl -X GET "${destinationUri}/destination-configuration/v1/subaccountDestinationFragments" \
  -H "Authorization: Bearer ${access_token}"

Create Fragment

POST /subaccountDestinationFragments

curl -X POST "${destinationUri}/destination-configuration/v1/subaccountDestinationFragments" \
  -H "Authorization: Bearer ${access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "my-fragment",
    "FragmentProperties": [
      {
        "Name": "URL.headers.X-Tenant-Id",
        "Value": "tenant-123"
      }
    ]
  }'

Delete Fragment

DELETE /subaccountDestinationFragments/{fragmentName}

curl -X DELETE "${destinationUri}/destination-configuration/v1/subaccountDestinationFragments/my-fragment" \
  -H "Authorization: Bearer ${access_token}"

Subscription-Level Destinations (Multitenancy)

For SaaS applications with tenant-specific destinations.

Create Subscription Destination

Get subscriber token using provider credentials
Call API with subscriber context

# Get subscriber token
curl -X POST "${subscriberTokenUrl}/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  --data-urlencode "client_id=${providerClientId}" \
  --data-urlencode "client_secret=${providerClientSecret}"

# Create subscription destination
curl -X POST "${destinationUri}/destination-configuration/v1/subscriptionDestinations" \
  -H "Authorization: Bearer ${subscriber_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "tenant-destination",
    "Type": "HTTP",
    "URL": "https://tenant-api.example.com",
    "Authentication": "BasicAuthentication",
    "User": "tenant-user",
    "Password": "tenant-password"
  }'

Pagination

For large numbers of destinations, use pagination:

GET /subaccountDestinations?$top=100&$skip=0

curl -X GET "${destinationUri}/destination-configuration/v1/subaccountDestinations?\$top=100&\$skip=0" \
  -H "Authorization: Bearer ${access_token}"

Parameters:

$top: Maximum number of results (default: 100)
$skip: Number of results to skip

Error Handling

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	Deleted
400	Bad Request (invalid payload)
401	Unauthorized (invalid/expired token)
403	Forbidden (insufficient permissions)
404	Not Found
409	Conflict (destination already exists)
500	Internal Server Error

Error Response Format

{
  "ErrorMessage": "Destination with name 'my-destination' already exists."
}

Best Practices

Caching

Cache access tokens for their validity period
Cache destination configurations (3-5 minutes recommended)
Use stale cache if refresh fails

Retry Logic

const retryDelays = [2000, 4000, 8000, 16000]; // ms

async function callWithRetry(fn) {
  for (let i = 0; i < retryDelays.length; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === retryDelays.length - 1) throw error;
      await sleep(retryDelays[i]);
    }
  }
}

Timeouts

Connect timeout: 2-5 seconds
Read timeout: ~30 seconds

SDK Usage

SAP Cloud SDK (Node.js)

const { getDestination } = require('@sap-cloud-sdk/connectivity');

// Get destination with authentication
const destination = await getDestination({
  destinationName: 'my-destination',
  jwt: userJwt  // For user propagation
});

console.log(destination.url);
console.log(destination.authTokens);

SAP Cloud SDK (Java)

import com.sap.cloud.sdk.cloudplatform.connectivity.DestinationAccessor;

// Get destination
Destination destination = DestinationAccessor
    .getDestination("my-destination");

String url = destination.get(DestinationProperty.URI)
    .orElseThrow();

Documentation Links

API Specification: https://api.sap.com/api/SAP_CP_CF_Connectivity_Destination
Calling the API: https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/calling-destination-service-rest-api
Multitenancy: https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/multitenancy-in-destination-service

Last Updated: 2025-11-22

/sap-btp-connectivity