Set the off-site copy destination

PUT

/clusters/{cluster_id}/backup-destination

const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/backup-destination';
const options = {
  method: 'PUT',
  headers: {
    'API-Version': '2026-06-01.beta',
    'API-Key': '<API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"bucket":"acme-keycloak-backups","region":"eu-central-1","access_key_id":"AKIAEXAMPLE","secret_access_key":"write-only"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/backup-destination \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta' \
  --header 'Content-Type: application/json' \
  --data '{ "bucket": "acme-keycloak-backups", "region": "eu-central-1", "access_key_id": "AKIAEXAMPLE", "secret_access_key": "write-only" }'

Creates or replaces the cluster’s one destination. After each completed backup the plain pg_restore archive is copied to <prefix>/<cluster_id>/<backup_id>.dump with its manifest <backup_id>.json beside it. Skycloak never deletes anything in your bucket.

Returns 403 on plans without off-site copy.

Required scope: clusters:backups:write

Authorizations

ApiKeyAuth

Parameters

Path Parameters

cluster_id

required

string format: uuid

Header Parameters

API-Version

required

string

Allowed values: 2026-06-01.beta

Request Body^required

application/json

object

endpoint

S3-compatible endpoint. Omit for AWS S3. Must be an https URL to a public host.

string

<= 512 characters

region

Signing region. Required when endpoint is set.

string

<= 512 characters

bucket

required

string

<= 512 characters

prefix

Optional key prefix for the copies.

string

<= 512 characters

access_key_id

required

string

<= 512 characters

secret_access_key

Secret access key. Required for a new destination and whenever the endpoint, bucket or access key changes; otherwise omit it to keep the stored one. Never returned.

string

<= 1024 characters

enabled

Defaults to true for a new destination; omit to keep the current value.

boolean

Example

{
  "bucket": "acme-keycloak-backups",
  "region": "eu-central-1",
  "access_key_id": "AKIAEXAMPLE",
  "secret_access_key": "write-only"
}

Responses

200

The request has succeeded.

application/json

Where finished backups are copied: one S3-compatible bucket you own. The secret access key is write-only and is never returned.

object

endpoint

S3-compatible endpoint, for example https://<account>.r2.cloudflarestorage.com. Omitted for AWS S3.

string

region

Signing region. Required with a custom endpoint.

string

bucket

required

string

prefix

Key prefix the copies are written under: <prefix>/<cluster_id>/<backup_id>.dump and .json.

string

access_key_id

required

string

enabled

required

Whether finished backups are copied. Turn off to pause copying without removing the destination.

boolean

last_tested_at

When Test connection last ran against this destination.

string format: date-time

last_test_ok

Whether the last Test connection succeeded.

boolean

last_test_error

The provider’s error from the last failed Test connection.

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "bucket": "acme-keycloak-backups",
  "region": "eu-central-1",
  "prefix": "skycloak",
  "access_key_id": "AKIAEXAMPLE",
  "enabled": true,
  "created_at": "2026-11-08T10:00:00Z",
  "updated_at": "2026-11-08T10:00:00Z"
}

401

Access is unauthorized.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

403

Access is forbidden.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

404

The server cannot find the requested resource.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

422

Client error

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

errors

required

Array<object>

>= 1 items

object

field

required

string

detail

required

string

code

string

value

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "errors": [
    {
      "field": "example",
      "detail": "example",
      "code": "example",
      "value": "example"
    }
  ]
}

429

Client error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Headers

Retry-After

integer

RateLimit-Limit

integer

RateLimit-Remaining

integer

RateLimit-Reset

integer

X-RateLimit-Limit-Second

integer

X-RateLimit-Remaining-Second

integer

X-RateLimit-Limit-Minute

integer

X-RateLimit-Remaining-Minute

integer

X-RateLimit-Limit-Hour

integer

X-RateLimit-Remaining-Hour

integer

X-RateLimit-Limit-Day

integer

X-RateLimit-Remaining-Day

integer

500

Server error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

501

Server error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Set the off-site copy destination

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Example

Responses

200

Example

401

Example generated

403

Example generated

404

Example generated

422

Example generated

429

Example generated

Headers

500

Example generated

501

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated