Credentials

Available now Producer apps connect themselves in the portal: no request to

RND, no deploy. Consumer and skill apps read a workspace's messages through consumer connections.

A connection is one app in one workspace. It carries what the app may send there (its system_ids and message types) and one credential: a client id and secret for the bus's token service. The same app in two workspaces has two connections and two secrets, so a leaked secret reaches one workspace only. A connection can also sign in as an AWS role or as a client of your own identity provider: see Authenticate.

Who can do what, per workspace:

	Viewer	Developer	Admin	Owner
See apps, their grants and credential details (never the secret)	✓	✓	✓	✓
Create apps, connect them, rotate and revoke secrets		✓	✓	✓
Register AWS roles, bind clients (Authenticate)		✓	✓	✓
Register your organisation's identity providers				✓

Every change is recorded in the workspace's audit log: who, what, when and from where. Secrets and tokens never are.

1. Create an app

In the portal, choose your workspace, open Apps and credentials and press New app.

• Name: lowercase letters, digits and hyphens, unique in your organisation, for example acme-ncs.
• Kind: producer, consumer or skill executor. A producer publishes; a consumer or skill executor reads from a consumer connection. To try a round trip, you need one of each.

The app belongs to your organisation, not to the workspace: it keeps one identity, and one history of verdicts, in every workspace it joins.

2. Connect it and get the secret

Press Connect on a producer app and choose:

• system_ids it stamps: the originating_system.system_id values the app may send. They are unique across the bus, first come, first served, and belong to your app in every workspace it joins. Prefix them with your organisation (acme-ncs-01, not ncs-01). An id another app holds is refused with system_id … belongs to another app.
• Message types it may publish: exact types (story.context) or a family (telling.*).

Connecting records your acceptance of the sandbox terms. The portal then shows, once:

Client id	Your connection id: c followed by 12 lowercase letters and digits
Client secret	Starts with sbs_. Only a hash is kept: a lost secret can't be shown again, only rotated
Token URL	https://api.sombus.rnd-solutions.net/v1/oauth/token
Publish to	https://api.sombus.rnd-solutions.net/v1/tenants/{t}/messages
Dry run	https://api.sombus.rnd-solutions.net/v1/tenants/{t}/validate

The browser tab that showed the secret also keeps it in memory, never in its storage, until you reload or sign out, so the Playground can publish with it without a paste.

{t} is your workspace id. Copy the secret into your secret store straight away; keep it out of source control and chat. The Preview environment has its own URLs and credentials (see Environments).

Then get a token and publish:

TOKEN=$(curl -s https://api.sombus.rnd-solutions.net/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials | jq -r .access_token)

curl -s https://api.sombus.rnd-solutions.net/v1/tenants/$WORKSPACE/validate \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' --data @message.json

Your app's permissions apply within about 30 seconds of connecting. Reuse a token for its hour; see Token service and workspace API for the details and limits.

3. Rotate the secret

Rotate on a schedule, when someone who knew the secret leaves, or when you suspect a leak. Press Rotate secret and choose how long the previous secret keeps working: 24 hours (the default), 3 days, 1 hour, or none.

What happens:

1. The portal shows the new secret, once.
2. Every token issued before the rotation stops working within about 30 seconds, whichever secret it came from. Your app gets 401 and should fetch a new token, as it would when a token expires.
3. During the overlap, both secrets get tokens. Move each running system to the new secret.
4. When the overlap ends the previous secret is refused. To end it early, press Stop old secret now.

Your workspace's owners get an email when fewer than 6 hours of an overlap are left (who gets it can be changed: see Notifications).

A suspected leak: rotate with none, so the old secret and its tokens stop at once.

Tokens carry a credential_version claim that goes up by one with each rotation; the bus refuses a token whose version isn't the credential's current one.

Only the organisation that owns an app rotates its secret. When your app is connected to a publisher's house, the house can disconnect it, but never sees or rotates its secret.

4. Revoke

Revoke ends the connection: its secret gets no more tokens at once, and tokens already issued are refused within about 30 seconds (403 producer.not_registered). Its AWS role and identity-provider client, if it has them, stop too, and are released for a new connection. The connection stays in the list as Revoked, for the record.

To use the app in the workspace again, press Connect again: you get a new connection, with a new client id and secret. The app keeps its system_ids.

If a consumer connection's filter names this connection as a source, the portal says so before you revoke: the new connection has a new id, so edit those filters to name it, or have them name the app's system_id instead.

Limits

• A connection has at most 20 system_ids and 30 message types.
• Each connection has its own request rate and daily allowance for bearer tokens on the workspace routes, so one busy app never spends another's. Requests signed with an AWS role share one limit across the bus instead. The numbers are in Limits.
• Changing a connection's system_ids or message types isn't in the portal yet: revoke it and connect again, or ask RND.

Next: Authenticate.