Activate a rail for the caller's tenant

curl --request PUT \
  --url https://api.example.com/v1/channels/{channelId}/activation \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/channels/{channelId}/activation"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PUT',
  headers: {'X-Idempotency': '<x-idempotency>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/v1/channels/{channelId}/activation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/channels/{channelId}/activation"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

response = requests.put(url, headers=headers)

print(response.text)

{
  "channelId": "spb",
  "registeredAt": "2023-11-07T05:31:56Z",
  "registeredBy": "<string>",
  "state": "REGISTERED",
  "tenantId": "<string>",
  "activatedAt": "2023-11-07T05:31:56Z",
  "activatedBy": "<string>",
  "suspendReason": "<string>",
  "suspendedAt": "2023-11-07T05:31:56Z",
  "suspendedBy": "<string>"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Activate a rail for the caller's tenant

Until a rail is active for a tenant the Courier carries none of its inbound traffic: the Pix ingress resolves no tenant and the SPB drain reads nothing from the vendor. Engine sends, queries and mailbox reads pass regardless; to stop an engine’s sends, disable the engine, which also stops its deliveries. Activating spb starts the drain of the vendor queue, whose read is destructive: from then on the Courier, not the engines, consumes it. The tenant is the caller’s, the validated identity’s in multi-tenant and local in single-tenant, and is returned as tenantId — the identifier an engine’s credential path names. The first activation records the operator as registeredBy; every activation that changes the state, first or resume, records it as activatedBy and in the rail’s history. Activating a suspended rail resumes it; an active one is returned unchanged and records nothing. A single-tenant Courier carries one tenant per rail: activating a rail another tenant holds active is refused 409 JDC-0117. Needs the admin grant (channels activation:write); channels write is not enough.

PUT

channels

{channelId}

activation

Activate a rail for the caller's tenant

curl --request PUT \
  --url https://api.example.com/v1/channels/{channelId}/activation \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/channels/{channelId}/activation"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PUT',
  headers: {'X-Idempotency': '<x-idempotency>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/v1/channels/{channelId}/activation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/channels/{channelId}/activation"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

response = requests.put(url, headers=headers)

print(response.text)

{
  "channelId": "spb",
  "registeredAt": "2023-11-07T05:31:56Z",
  "registeredBy": "<string>",
  "state": "REGISTERED",
  "tenantId": "<string>",
  "activatedAt": "2023-11-07T05:31:56Z",
  "activatedBy": "<string>",
  "suspendReason": "<string>",
  "suspendedAt": "2023-11-07T05:31:56Z",
  "suspendedBy": "<string>"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency

string

requerido

Idempotency key; a retry with the same key replays the first answer.

Parámetros de ruta

channelId

enum<string>

requerido

The rail. Closed vocabulary — a value outside it is a 404, never a new rail.

Opciones disponibles:

spb,

pix

Respuesta

channelId

enum<string>

requerido

Opciones disponibles:

spb,

pix

registeredAt

string<date-time>

requerido

registeredBy

string

requerido

The operator who first activated the rail for the tenant.

Maximum string length: 128

state

enum<string>

requerido

Only an ACTIVE rail carries the tenant's inbound traffic.

Opciones disponibles:

REGISTERED,

ACTIVE,

SUSPENDED

tenantId

string

requerido

The caller's tenant: the validated identity's in multi-tenant, local in single-tenant. The identifier an engine's credential path names.

Maximum string length: 255

activatedAt

string<date-time>

When the rail last began carrying inbound traffic.

activatedBy

string

The operator who last activated or resumed the rail. Absent on an activation that predates the rail audit.

Maximum string length: 128

suspendReason

string

Maximum string length: 512

suspendedAt

string<date-time>

suspendedBy

string

The operator who suspended the rail. Absent when not suspended, or suspended before the rail audit.

Maximum string length: 128

Motores

Mapa de titularidad

API de los motores

Canales

Mensajes

Registro de envíos

Conciliación

Manejo de errores

Activate a rail for the caller's tenant

Autorizaciones

Encabezados

Parámetros de ruta

Respuesta