Skip to content

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:

curl https://api.streetscapes.ai/v1/metadata \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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