Authentication¶
The API accepts a Cognito-issued bearer token on every request (except GET /hello). How you obtain it depends on whether you're a program or a person.
A request with no Authorization header is refused with 401, and one whose token is invalid or expired with 403, before any endpoint runs.
Machine-to-machine (app clients)¶
Programs authenticate with the OAuth 2.0 client-credentials flow using an app client's client_id and client_secret (created in the Portal):
curl -s -u "$DORY_CLIENT_ID:$DORY_CLIENT_SECRET" \
-d 'grant_type=client_credentials' \
-d 'scope=metadata/read:all subscriptions/read:self subscriptions/write:self subscriptions/delete:self rabbitmq/read:all' \
https://auth.streetscapes.ai/oauth2/token
The response contains an access_token. Send it on each API call:
The Application SDK performs this exchange for you — you only provide the client ID and secret. It asks for exactly the five scopes in the example above.
Scopes¶
A token carries scopes of the form resource/action:reach. Every app client you create draws its scopes from one fixed set:
| Scope | Grants |
|---|---|
metadata/read:all |
Read platform metadata (valid event types, the event-stream endpoint) |
subscriptions/read:self |
List the subscriptions this app client created, and read one of them (status, coverage report, error code) |
subscriptions/write:self |
Create subscriptions |
subscriptions/delete:self |
Delete subscriptions this app client created |
rabbitmq/read:all |
Consume from delivery queues. This one is checked by the event stream when the connection opens, not by the API |
appclients/read:all, appclients/write:all |
Read, create and update the organization's app clients (deleting one is not included) |
An app client created in the portal holds the whole set. One created through the API may be given fewer, never others — a scope outside the set is refused.
The API reads the resource/action part of a scope as the permission of the same name: subscriptions/write:self lets the call through the same subscriptions:write check a member's role goes through. The reach then limits how far that permission goes. For subscriptions it is always :self, because no app client can be given a subscription scope ending in :all: an app client can act only on the subscriptions it created. See Subscriptions: whose they are.
Portal users¶
People sign in through the portal's hosted Cognito flow; the portal holds the resulting access token and attaches it to API calls. User authorization is role-based — the token resolves to the user's roles in the organization being acted on, and each endpoint checks the corresponding resource:action permission. For subscriptions those are subscriptions:read and subscriptions:delete; ownership does not apply to members, so the role alone decides which of the organization's subscriptions they can read or delete. See Identity & Access and Portal: roles & permissions.
Subscriptions: whose they are¶
A subscription belongs to the app client that created it. The portal lists and deletes subscriptions, but does not create them.
| Endpoint | App client needs | Member needs |
|---|---|---|
POST /subscriptions |
subscriptions/write:self |
— (subscriptions are created by app clients) |
GET /subscriptions |
subscriptions/read:self |
subscriptions:read |
GET /subscriptions/{id} |
subscriptions/read:self |
subscriptions:read |
DELETE /subscriptions/{id} |
subscriptions/delete:self |
subscriptions:delete |
- Create. The organization comes from the credential, never from the request body. The permission is checked before the lens or anything else is looked up, so a caller without it cannot use later refusals to learn what exists.
- List. An app client gets only the subscriptions it created. A portal user names the organization and the app client whose subscriptions they want to see.
- One subscription, by id. The subscription is loaded first, because it is what says which organization to check. The answers come in this order:
| The subscription… | Answer |
|---|---|
| does not exist, has been deleted, or belongs to another organization | 404 — the same for all three, so nothing reveals that an id exists elsewhere |
| is in the caller's organization, but the caller lacks the permission | 403 |
| was created by a different app client in the same organization, and the caller is an app client | 403 — "You can only read subscriptions you created" / "You can only delete subscriptions you created" |
| was created by the calling app client, or the caller is a member with the permission | Proceeds |
The difference between 404 and 403 matters to programs: 404 means the subscription is gone (or was never yours to see), while 403 means it still exists and belongs to someone else. The Application SDK relies on it — it treats a 404 on unsubscribe as already gone, and keeps its record of a subscription it was refused with 403. The full flow is drawn on the Subscriptions page.
Choosing a caller type¶
| If you are… | Authenticate as | Authorized by |
|---|---|---|
| A backend/integration consuming events | App client (M2M) | OAuth scopes |
| A person managing the organization | Portal user | Role permissions |