Authenticate

A producer app publishes through a connection: the app in one workspace, with its grants (see Credentials). A connection can sign in three ways. All three reach the same checks: the bus maps the caller to exactly one connection, and that connection's workspace, system_ids and message types decide what it may publish.

Method	Status	For	Where you set it up
Client id and secret	Available now	Any system	Connect the app (Credentials)
AWS IAM role or user (SigV4)	Available now	Systems that already run in AWS: no secret to store	Sign-in methods on the connection
A client of your own identity provider	Available now	Organisations with Entra ID, Okta, Auth0, Keycloak or another OpenID provider	Your identity providers on the Apps page, then Sign-in methods

The last two are added to a connection that already exists: connect the app first. Each connection has at most one AWS principal and one identity-provider client, besides its secret. Only the organisation that owns the app sets them up, and a developer, admin or owner of the workspace does it; registering or removing the organisation's identity provider itself needs a workspace owner. Every change is in the workspace's audit log; tokens and challenges never are.

Revoking the connection ends all three at once, and releases the AWS principal and the client so they can be set up on a new connection.

Client id and secret

The default. Connect the app in the portal, keep the secret in your secret store, get a one-hour token from the bus's token service and send it as Authorization: Bearer <token> to /v1/tenants/{t}/messages. See Credentials and Token service and workspace API.

AWS IAM role (SigV4)

For a system that runs in AWS with a role of its own, such as a container task, a function or an instance profile. It signs its requests with its AWS credentials, so there's no secret to store or rotate.

1. Register the role

In the portal, open Apps and credentials, press Sign-in methods on the connection, and enter the ARN of the IAM role (or IAM user) your system runs as. Paste either the role's ARN or the ARN your system sees for itself (an assumed-role session): the bus stores the role, without its path.

The role is now awaiting proof. Until it proves it's yours, every request it signs is refused with principal.not_verified. That stops anyone from registering a role they don't control.

2. Prove control

The portal shows a one-time challenge and a ready-to-copy command. Run it with the role's credentials within 30 minutes: it signs a request to /v1/tenants/{t}/principals/verify with SigV4, carrying the challenge. The bus checks that the signer is the registered role, in this workspace, with the current challenge, and marks the role Verified.

{ "verified": true, "principal": "<the role>", "connection_id": "c…", "workspace_id": "w…" }

A refusal has its own shape, not the gateway's:

{ "verified": false, "code": "challenge.expired", "message": "The challenge has expired. Ask for a new one in the portal." }

Answer	Meaning
400 request.invalid	The body isn't JSON
400 challenge.invalid	The body doesn't carry a challenge: send {"challenge":"sbp_…"}
403 principal.unsupported	Signed as an account root or a federated user. Sign as an IAM role (or user)
403 principal.not_registered	Signed by another role, or for another workspace, or its connection is no longer active
403 challenge.invalid	Not the current challenge (it was replaced, or mistyped)
403 challenge.expired	Press New challenge in the portal and run the new command
409 challenge.invalid	The challenge changed or was used while you verified. Copy the current one and run again

The challenge is shown once and only a hash of it is kept.

3. Publish

Sign each request with SigV4 (your AWS SDK or any SigV4 client does this; the service name is in the command the portal shows) and send it to the signed routes:

Route	Purpose
POST /v1/tenants/{t}/iam/messages	Publish, exactly like /v1/tenants/{t}/messages
POST /v1/tenants/{t}/iam/validate	Dry run, exactly like /v1/tenants/{t}/validate

Answers and rules are the same as with a token. A role registered in one workspace is refused in any other with producer.not_registered. A role's permission to publish applies within about 30 seconds of verifying; removing the role, or revoking the connection, stops it within about 30 seconds.

Your AWS account must allow the role to call the bus API (Invoke on it). A role in the same account as another organisation's registration of it changes nothing for you: registrations are per workspace.

Limits

Signed requests can't use a per-connection allowance yet: that is tied to tokens. The signed routes have a limit shared by every AWS signer on the bus, plus the firewall's per-address limits, and no daily quota per connection. Another organisation's busy role can therefore slow yours down with 429s; a per-connection allowance for signed requests is planned.

What	Limit
/v1/tenants/{t}/iam/…, all signers together	50 requests a second, bursts of 100
The verify route, everyone together	2 requests a second, bursts of 5
Any route, per source address	600 requests a minute

For heavy test runs, use a token: its limits are your connection's own (Limits).

Your own identity provider

For organisations whose systems already get OAuth2 client-credentials tokens from their own identity provider. You register the provider once for your organisation, then bind each client to a connection by showing a token it got.

1. Register your identity provider

A workspace owner does this: the provider is trusted for clients bound in every workspace of your organisation. Developers and admins see the registered providers and bind clients to them (step 2).

On the Apps page, under Your identity providers, press Add identity provider:

Field
Issuer URL	Exactly the iss of your tokens. HTTPS, on a public host
Tokens must carry	An audience (aud) or a scope: the one your provider puts in tokens for the bus
Claim that names the client	Default sub. For example azp, appid or client_id, depending on your provider
Key set URL	Optional. By default the bus finds it through OpenID discovery (/.well-known/openid-configuration)

The bus fetches your provider's signing keys once when you register it, so a typo shows up at once. It fetches only from public HTTPS addresses, follows no redirects, and gives up after 3 seconds or 64 KiB. Keys are cached for 10 minutes; a new key id is picked up on its first use.

Up to three providers per organisation. A workspace owner removes one once no client is bound to it. The bus's own token service and its own sign-in can't be registered. Several organisations may register the same provider (a shared one): each is trusted only for its own clients.

2. Bind a client to a connection

Get a token for the client from your provider, with the client's own credentials, and within 15 minutes paste it into Sign-in methods on the connection, under Your identity provider. The bus checks it against your registered provider (signature, issuer, audience or scope, expiry, issued in the last 15 minutes), reads the client from the claim you chose, and binds that client to the connection. The token isn't kept.

Nobody can bind a client they can't get a token for, and a client binds to one connection on the whole bus: a second binding is refused until the first is removed.

3. Publish

The client gets tokens from your provider as usual and sends them as Authorization: Bearer <token> to /v1/tenants/{t}/messages and /validate. The bus accepts them only for the connection the client is bound to, and only because your organisation registered the provider. Answers, rules and limits are those of the token routes: the connection's own allowance applies.

Unbind the client, or revoke the connection, and its tokens are refused within about 30 seconds. A provider with bound clients can't be removed; unbind them first.

Which to choose

• Client secret works everywhere and is the simplest to start with.
• AWS role when your system runs in AWS: nothing to store or rotate, but a shared route limit.
• Your identity provider when your organisation manages machine identities centrally: rotate and revoke clients where you manage everything else, with the connection's own limits.

Good practice, whichever you choose

• Keep secrets server-side, in a secret store: never in client code, a repository or chat.
• Credentials belong to one environment. A Sandbox token or registration is refused on Preview, and the reverse.
• The credential identifies your connection, nothing more. What it may send is looked up on every request, so a change to its grants or a revocation needs no new token and applies within about 30 seconds.
• A missing, malformed or expired token is 401producer.unauthenticated. A valid one whose connection isn't active is 403 producer.not_registered.
• A bad AWS signature (unsigned, badly signed or with expired AWS credentials) is answered by AWS in front of the bus, with 403 and a body of the form {"message":"…"} rather than the bus's usual shape. Refresh your AWS credentials and check the signing.

Apps RND manages for you Via RND

Some apps were registered by RND in the bus configuration, before workspaces. They authenticate the old way, and RND manages their credentials:

Route	Credentials
POST /v1/jwt/messages	A bearer token from the token URL RND sent you: HTTP Basic with the client id and secret, grant_type=client_credentials, scope sombus/publish. Tokens last one hour
POST /v1/messages	AWS SigV4, signed with an IAM role RND registered for your app

Both take the same body and give the same answers as the workspace routes, but their traffic isn't in a workspace. RND rotates or replaces their credentials on request: tokens already issued keep working until they expire, within the hour. To manage an app yourself, connect it in your workspace (Credentials).

Next: Send your first message.