Register a site

POST

/v1/projects/{projectId}/sites

const url = 'https://example.com/v1/projects/example/sites';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"displayName":"example","origin":"example","approvalsUrl":"example","allowedRoles":["example"],"roleMap":{"additionalProperty":{"ask":true,"reviewer":"standard"}},"reviewerCeiling":"standard","vouching":true,"peopleCap":1,"newPeoplePerDay":1}'
};

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

curl --request POST \
  --url https://example.com/v1/projects/example/sites \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "displayName": "example", "origin": "example", "approvalsUrl": "example", "allowedRoles": [ "example" ], "roleMap": { "additionalProperty": { "ask": true, "reviewer": "standard" } }, "reviewerCeiling": "standard", "vouching": true, "peopleCap": 1, "newPeoplePerDay": 1 }'

A site that will sign its own people in to this project, and a one-time enrollment code for it, shown once: the site posts it with its public key (POST /v1/auth/sites/enroll). Until then it has no key and signs nobody in. A role map gives no reviewer role above reviewerCeiling, and names only allowedRoles; nothing it gives reaches above the project. Tenant admins only.

Authorizations

bearerAuth

Parameters

Path Parameters

projectId

required

string

ProjectId — opaque branded string.

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Request Body^required

application/json

object

displayName

required

string

>= 1 characters <= 100 characters

origin

required

An https:// origin with no path; http:// only for localhost, 127.0.0.1 or [::1].

string

approvalsUrl

required

A URL on the site’s own origin with {approvalId} in it.

string

allowedRoles

The roles that may sign in at all. Default ["administrator", "shop_manager"].

Array<string>

>= 1 items <= 20 items

roleMap

Default: both default roles may ask, and decide as standard reviewers. Without a roleMap, the map keeps only the entries of the roles in allowedRoles: the default map’s for a new site, the site’s own for a change. An allowed role with no entry signs in to read the project only.

object

key

additional properties

What a person with one of the site’s roles gets in the site’s project. Reading the project comes with every role; nothing above it ever does.

object

ask

required

Whether they may start turns with the project’s agents.

boolean

reviewer

The reviewer role they decide approvals with, at most the site’s reviewerCeiling; absent: they decide none.

string

Allowed values: standard senior

reviewerCeiling

Default standard.

string

Allowed values: standard senior

vouching

Default true.

boolean

peopleCap

Default 50.

integer

>= 1 <= 10000

newPeoplePerDay

Default 20.

integer

>= 1 <= 1000

Responses

201

The site, and its enrollment code.

application/json

object

site

required

A site that signs its own people in to one project: it vouches for whoever is signed in there, so they ask the project’s agents and decide its approvals as themselves. Each person it signs in is a person of the tenant, shown as “, via ”.

object

siteId

required

string format: uuid

projectId

required

string format: uuid

displayName

required

Set by a tenant admin, never by the site: shown after every name the site signs in.

string

origin

required

The site’s origin (https://acme-store.example).

string

approvalsUrl

required

Where an approval opens on the site; {approvalId} is replaced. A site’s people get it in their reviewer email.

string

allowedRoles

required

Array<string>

roleMap

required

Role → grant. A person with several allowed roles gets the most any of them gives.

object

key

additional properties

What a person with one of the site’s roles gets in the site’s project. Reading the project comes with every role; nothing above it ever does.

object

ask

required

Whether they may start turns with the project’s agents.

boolean

reviewer

The reviewer role they decide approvals with, at most the site’s reviewerCeiling; absent: they decide none.

string

Allowed values: standard senior

reviewerCeiling

required

string

Allowed values: standard senior

vouching

required

Whether the site’s statements are accepted.

boolean

peopleCap

required

At most this many live people from the site.

integer

>= 1

newPeoplePerDay

required

At most this many new people from the site per day.

integer

>= 1

keys

required

Array<object>

One of the site’s live public keys. Kindgi never has a private half.

object

kid

required

string

thumbprint

required

The key’s RFC 7638 thumbprint, to compare with the one the site shows.

string

addedAt

required

string format: date-time

audience

What the site’s statements carry as aud: this deployment’s public URL, given at enrollment.

string

createdAt

required

string format: date-time

createdBy

string

pausedAt

string format: date-time

unregisteredAt

string format: date-time

enrollment

required

A one-time code the site posts with its public key (POST /v1/auth/sites/enroll). Shown once. Using it replaces the site’s keys and ends its live sessions.

object

code

required

string

expiresAt

required

string format: date-time

Example

{
  "site": {
    "roleMap": {
      "additionalProperty": {
        "reviewer": "standard"
      }
    },
    "reviewerCeiling": "standard"
  }
}

400

A setting the site can’t have (site-invalid, details.field): an origin that isn’t https, an approvals URL on another origin, a role map above the ceiling or over a role that isn’t allowed.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Not a tenant admin.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No project with that id (project-not-found).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Idempotency-Key reused with a different body (idempotency-key-body-mismatch), or a retry of a request that succeeded: its answer carried a secret, which isn’t kept (idempotency-key-replay-withheld).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Register a site

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

413

Examplegenerated

500

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated