Connect or replace a domain service

PUT

/v1/domain/services/{serviceId}

• Production

The services of the caller’s domain (Bkper’s verified domain of the account), used by every member’s agent after their own services for the same host. Through an App or channel bot, 404. Only the domain’s admin: 403 domain_admin_required for anyone else, members included. As PUT /v1/services/{serviceId}, within the domain: 409 host_in_use when another of the domain’s services holds a host, 409 service_limit at 20 services. A domain’s secret works for every member and any App they authorize.

Authorizations

• bearerAuth

Parameters

Path Parameters

serviceId

required

string

/^[a-z0-9][a-z0-9-]{0,63}$/

Request Body ^required

object

name

required

Display name, such as GitHub.

string

>= 1 characters <= 64 characters /^[^\u0000-\u001f\u007f]*$/

targets

required

1 to 10 hosts, each once. A service with a google target has only google targets.

Array

>= 1 items <= 10 items

One of:

object

object

host

required

An exact lowercase DNS name with at least two labels, reached over HTTPS on its default port: no wildcard, port, path, IP literal or localhost. Bkper and Cloudflare Artifacts hosts are refused (400 host_not_allowed): they have their own routes.

string

/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/

scheme

required

string

Allowed value: bearer

object

object

host

required

An exact lowercase DNS name with at least two labels, reached over HTTPS on its default port: no wildcard, port, path, IP literal or localhost. Bkper and Cloudflare Artifacts hosts are refused (400 host_not_allowed): they have their own routes.

string

/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/

scheme

required

string

Allowed value: basic

username

required

Basic only: the username sent with the secret. No colon.

string

>= 1 characters <= 128 characters /^[^\x00-\x1f\x7f:]+$/

object

object

host

required

An exact lowercase DNS name with at least two labels, reached over HTTPS on its default port: no wildcard, port, path, IP literal or localhost. Bkper and Cloudflare Artifacts hosts are refused (400 host_not_allowed): they have their own routes.

string

/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/

scheme

required

string

Allowed value: header

header

required

Header only: the header that carries the secret, such as x-api-key. Not host, content-length, transfer-encoding, connection.

string

/^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,64}$/

object

object

host

required

Google only: a Google API host, ending in .googleapis.com, such as analyticsdata.googleapis.com. Not oauth2.googleapis.com (400 host_not_allowed).

string

/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/

scheme

required

string

Allowed value: google

google

Google services only, and always with google targets: the scopes their access tokens are made for.

object

scopes

required

1 to 20 OAuth scopes, each https://www.googleapis.com/auth/…, such as https://www.googleapis.com/auth/analytics.readonly.

Array<string>

>= 1 items <= 20 items

secret

required

Up to 8192 characters. A token: printable ASCII, without spaces at either end. For google, the service account’s JSON key file as it is (400 invalid_request when it is not a service account key). Write-only: never returned, logged or shown to the agent.

string

>= 1 characters <= 8192 characters

Responses

200

Replaced

A service the user connected: requests the agent sends to its hosts carry the stored secret, added outside the sandbox. The secret is never returned.

object

id

required

string

name

required

string

targets

required

Array<object>

object

host

required

string

scheme

required

How the secret is sent. Open: bearer | basic | header | google.

string

username

Basic only.

string

header

Header only.

string

google

Google services only.

object

scopes

required

Array<string>

clientEmail

required

The service account’s email, read from its key: share what the agent should reach with it.

string

createdAt

required

Milliseconds since the epoch, as a string.

string

/^\d+$/

updatedAt

required

Milliseconds since the epoch, as a string.

string

/^\d+$/

201

Connected

A service the user connected: requests the agent sends to its hosts carry the stored secret, added outside the sandbox. The secret is never returned.

object

id

required

string

name

required

string

targets

required

Array<object>

object

host

required

string

scheme

required

How the secret is sent. Open: bearer | basic | header | google.

string

username

Basic only.

string

header

Header only.

string

google

Google services only.

object

scopes

required

Array<string>

clientEmail

required

The service account’s email, read from its key: share what the agent should reach with it.

string

createdAt

required

Milliseconds since the epoch, as a string.

string

/^\d+$/

updatedAt

required

Milliseconds since the epoch, as a string.

string

/^\d+$/

400

Rejected; never contains credentials or upstream payloads.

object

error

required

object

code

required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string

type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string

message

string

host

Host_in_use: the host another service holds.

string

service

Host_in_use: the id of the service that holds the host.

string

401

Rejected; never contains credentials or upstream payloads.

object

error

required

object

code

required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string

type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string

message

string

host

Host_in_use: the host another service holds.

string

service

Host_in_use: the id of the service that holds the host.

string

403

Rejected; never contains credentials or upstream payloads.

object

error

required

object

code

required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string

type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string

message

string

host

Host_in_use: the host another service holds.

string

service

Host_in_use: the id of the service that holds the host.

string

404

Rejected; never contains credentials or upstream payloads.

object

error

required

object

code

required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string

type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string

message

string

host

Host_in_use: the host another service holds.

string

service

Host_in_use: the id of the service that holds the host.

string

409

Rejected; never contains credentials or upstream payloads.

object

error

required

object

code

required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string

type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string

message

string

host

Host_in_use: the host another service holds.

string

service

Host_in_use: the id of the service that holds the host.

string

410

Rejected; never contains credentials or upstream payloads.

object

error

required

object

code

required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string

type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string

message

string

host

Host_in_use: the host another service holds.

string

service

Host_in_use: the id of the service that holds the host.

string

411

Rejected; never contains credentials or upstream payloads.

object

error

required

object

code

required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string

type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string

message

string

host

Host_in_use: the host another service holds.

string

service

Host_in_use: the id of the service that holds the host.

string

413

Rejected; never contains credentials or upstream payloads.

object

error

required

object

code

required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string

type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string

message

string

host

Host_in_use: the host another service holds.

string

service

Host_in_use: the id of the service that holds the host.

string

503

Rejected; never contains credentials or upstream payloads.

object

error

required

object

code

required

Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open.

string

type

Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.

string

message

string

host

Host_in_use: the host another service holds.

string

service

Host_in_use: the id of the service that holds the host.

string