Save (or rotate) a connection's credentials

curl --request PUT \
  --url https://api.royalti.io/capabilities/{slug}/credentials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apiKey": "9JP4FKWP0TMTDFPYHGSEIUGFBWEFHGSLQVSHJF2KTR17HGSGHFKHGDBSJFVG",
  "clientId": "H812JHVLSDKJFBVKLJDBSFVBDFUVS86Y5"
}
'

{
  "status": "success",
  "message": "Credentials saved",
  "data": {
    "slug": "paystack",
    "kind": "connection",
    "name": "VertoFX",
    "description": "Send cross-border payouts and manage beneficiaries through VertoFX.",
    "enabled": true,
    "settings": {},
    "settingsVersion": 1,
    "settingsSchema": {},
    "hasCredentials": true,
    "credentialShape": [
      "apiKey",
      "clientId"
    ],
    "requiresConfig": true,
    "connectionStatus": {
      "connected": true,
      "message": "<string>",
      "availablePeriods": [
        "202401",
        "202402",
        "202403"
      ],
      "dspFolders": [
        "DistroKid",
        "CD Baby",
        "TuneCore"
      ]
    },
    "lastConnectionTest": "2023-11-07T05:31:56Z",
    "connectionError": "<string>",
    "features": {
      "royaltyImport": true,
      "invoiceImport": false
    }
  }
}

PUT

capabilities

{slug}

credentials

curl --request PUT \
  --url https://api.royalti.io/capabilities/{slug}/credentials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apiKey": "9JP4FKWP0TMTDFPYHGSEIUGFBWEFHGSLQVSHJF2KTR17HGSGHFKHGDBSJFVG",
  "clientId": "H812JHVLSDKJFBVKLJDBSFVBDFUVS86Y5"
}
'

{
  "status": "success",
  "message": "Credentials saved",
  "data": {
    "slug": "paystack",
    "kind": "connection",
    "name": "VertoFX",
    "description": "Send cross-border payouts and manage beneficiaries through VertoFX.",
    "enabled": true,
    "settings": {},
    "settingsVersion": 1,
    "settingsSchema": {},
    "hasCredentials": true,
    "credentialShape": [
      "apiKey",
      "clientId"
    ],
    "requiresConfig": true,
    "connectionStatus": {
      "connected": true,
      "message": "<string>",
      "availablePeriods": [
        "202401",
        "202402",
        "202403"
      ],
      "dspFolders": [
        "DistroKid",
        "CD Baby",
        "TuneCore"
      ]
    },
    "lastConnectionTest": "2023-11-07T05:31:56Z",
    "connectionError": "<string>",
    "features": {
      "royaltyImport": true,
      "invoiceImport": false
    }
  }
}

This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

merlin) — any other slug returns 400. The body must contain only keys named in the capability’s credentialShape; every previous credential value is replaced (there is no partial credential patch). After saving, the capability’s connection test runs automatically when it has one, and the response reflects the fresh connectionStatus. Authorization:

Required role: owner only

Code Examples

const response = await fetch('https://api.royalti.io/capabilities/{slug}/credentials', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
});

const data = await response.json();
console.log(data);

import requests

response = requests.put(
  'https://api.royalti.io/capabilities/{slug}/credentials',
  headers={
    'Authorization': f'Bearer {token}'
  },
  json={}
)

data = response.json()
print(data)

curl -X PUT https://api.royalti.io/capabilities/{slug}/credentials \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Authorizations

Authorization

string

header

required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Path Parameters

slug

enum<string>

required

Stable identifier; never renamed after ship.

Available options:

paystack,

vertofx,

merlin,

ddex-delivery,

publisher,

distro,

release,

payment-requests,

email-branding,

catalog-media

Body

application/json

Only the keys in the target capability's credentialShape.

Response

Credentials saved (and tested, when the capability has a connection test)

status

string

Example:

"success"

message

string

Example:

"Credentials saved"

data

object

One entry in GET /capabilities data, and the shape of every write response's data.

Show child attributes

​Description

​Code Examples

Authorizations

Path Parameters

Body

Response

Description

Code Examples