Connect or replace a service

PUT

/v1/services/{serviceId}

• Production

Only with the user’s own token: through an App or channel bot, 404. Replaces the whole service, its secret always included; 201 when it is new. 409 host_in_use when another service holds a host, 409 service_limit at 20 services, 503 service_unavailable when it cannot be stored encrypted.

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