Authentication¶
The Application SDK authenticates with the OAuth 2.0 client-credentials flow and handles tokens for you. You supply an app client's client_id and client_secret; the SDK does the rest. One token serves both halves of the SDK: it is the bearer token on every API call and the password on the broker connection that delivers your events. For the platform-wide model, see Identity & Access.
Supplying credentials¶
Two ways, in order of preference:
# 1. Environment variables (recommended — keeps secrets out of code)
# export DORY_CLIENT_ID="..."
# export DORY_CLIENT_SECRET="..."
from dory import DoryClient
client = DoryClient()
# 2. Directly in code
client = DoryClient(client_id="your client id", client_secret="your client secret")
If neither a constructor argument nor an environment variable is found, construction raises AuthError (importable from dory):
Client ID and Client Secret must be provided either via constructor or environment variables (DORY_CLIENT_ID, DORY_CLIENT_SECRET)
What happens under the hood¶
sequenceDiagram
participant App as Your app (SDK)
participant Token as Token endpoint
participant API as Dory API
participant MQ as Message broker
Note over App: DoryClient() is constructed
App->>Token: POST /oauth2/token<br/>Basic auth: client_id : client_secret<br/>grant_type=client_credentials<br/>scope = the five scopes
Token-->>App: access token + lifetime (expires_in)
Note over App: cached until 60 s before expiry
App->>API: GET /metadata<br/>Authorization: Bearer token
API-->>App: event types, broker endpoint
Note over App: later, subscribe()
App->>API: POST /subscriptions<br/>Authorization: Bearer token
API-->>App: 202 subscriptionId, queueName
App->>MQ: AMQPS connect<br/>username: (empty) · password: the token
MQ-->>App: consume from the delivery queue
Note over App,MQ: near expiry the next call mints a new token.<br/>A broker connection opened later uses whatever token is current
- Token. On construction,
DoryClientsends one request to the token endpoint (DORY_COGNITO_DOMAINwith/oauth2/tokenappended): HTTP Basic auth withclient_idandclient_secret,grant_type=client_credentials, and ascopeparameter naming the five scopes in the next section. The request is bounded byDORY_HTTP_TIMEOUT(default 10 seconds). - API calls. The token goes out as
Authorization: Bearer …on every API call — the metadata read at construction, thensubscribe(),list_subscriptions(),get_subscription()andunsubscribe(), andwait_until_ready()when its wait runs out and it asks the API. - Delivery. Each
subscribe()opens its own broker connection over AMQPS (TLS) with an empty username and the access token as the password; the broker authenticates the token alone. That is the detail to copy if you ever open the connection with another AMQP client. - Caching. The token is minted once and reused until 60 seconds before the lifetime the token endpoint advertised; the first call after that mints a new one. A broker connection opened later uses whatever token is current at that moment.
You never see or store the token.
Scopes the SDK requests¶
The client-credentials request always asks for exactly these five scopes: enough to read platform metadata, manage the subscriptions this app client creates, and consume their events.
| Scope | Purpose |
|---|---|
metadata/read:all |
Read platform metadata (valid event types, broker endpoint) |
subscriptions/read:self |
List your subscriptions, and read one subscription's status and coverage report (list_subscriptions(), get_subscription(), wait_until_ready()) |
subscriptions/write:self |
Create subscriptions (subscribe()) |
subscriptions/delete:self |
Delete subscriptions it owns (unsubscribe()) |
rabbitmq/read:all |
Connect to the message broker and consume from your delivery queues. This is the SDK's only broker scope: the platform creates, binds and removes the queues with its own identity, so a consuming token cannot declare queues or bindings |
Two places check these scopes. The Dory API checks the one scope each call needs: the metadata read needs metadata/read:all, subscribe() needs subscriptions/write:self, and so on. The message broker checks rabbitmq/read:all when a connection is opened.
flowchart LR
T["Access token<br/>(five scopes)"]
T --> M["metadata/read:all"]
T --> R["subscriptions/read:self"]
T --> W["subscriptions/write:self"]
T --> D["subscriptions/delete:self"]
T --> Q["rabbitmq/read:all"]
subgraph API["Checked by the Dory API, per call"]
M --> M1["GET /metadata<br/>(on construction)"]
R --> R1["list_subscriptions()<br/>get_subscription() · wait_until_ready()"]
W --> W1["subscribe()"]
D --> D1["unsubscribe()"]
end
subgraph MQ["Checked by the message broker on connect"]
Q --> Q1["Connect and consume from<br/>your delivery queues<br/>(cannot declare queues or bindings)"]
end
R1 -. ":self — only subscriptions this app client created" .- D1
What the SDK does not ask for¶
- App-client management. By default an app client is also created with
appclients/read:allandappclients/write:all, which manage your organization's app clients. The SDK does not request them, because none of its calls needs them. - Broker administration.
rabbitmq/read:allis the only broker scope the SDK requests. It never asks forrabbitmq/write:all,rabbitmq/configure:allorrabbitmq/tag:administrator, and no app client can be granted them: a request to create an app client with a scope outside its fixed set is refused. Setting up queues and publishing events are done by identities the platform keeps to itself. See Identity on the event stream.
Use an app client that holds all five
The SDK always asks for all five scopes. An app client created in the portal holds every one of them. An app client created through the API with a shorter scope list may be missing one, and scopes cannot be changed after creation. If yours is missing one, create a new app client that holds all five and move your program over.
What :self means in practice¶
The :self suffix means the client can only see and delete subscriptions it created. See Identity & Access. Concretely:
| The subscription… | What the API answers | What the SDK does |
|---|---|---|
| was created by this app client | 200 / 202 | Every call works; list_subscriptions() returns only these |
| was created by another app client in your organization | HTTP 403 — You can only read subscriptions you created / You can only delete subscriptions you created |
get_subscription() raises RuntimeError, as does wait_until_ready() once its timeout elapses; unsubscribe() raises RuntimeError and keeps its local entry — the subscription still exists and still belongs to the client that made it |
| does not exist, or belongs to another organization | HTTP 404 | The reads raise SubscriptionNotFound; unsubscribe() treats it as already gone and returns normally |
The checks run in that order — existence in your organization first, then ownership — which is why a subscription outside your organization looks like a missing one rather than a forbidden one:
flowchart TD
S["get_subscription(id) · wait_until_ready(id) · unsubscribe(id)"] --> E{"Does the subscription exist<br/>in your organization?"}
E -- "no, or it belongs to another organization" --> N["HTTP 404<br/>reads raise SubscriptionNotFound<br/>unsubscribe() treats it as already gone"]
E -- yes --> O{"Was it created by<br/>this app client?"}
O -- no --> F["HTTP 403 — you can only read/delete subscriptions you created<br/>the SDK raises and unsubscribe() keeps its local entry"]
O -- yes --> P["Proceeds"]
The full list of errors each call can raise is in Managing Subscriptions.
Endpoints¶
By default the SDK talks to the production platform. The token endpoint (DORY_COGNITO_DOMAIN, with /oauth2/token appended), the API root (DORY_API_ROOT_URL) and the per-request timeout that also bounds the token request (DORY_HTTP_TIMEOUT, default 10 seconds) are all overridable through environment variables — see Configuration for the table.
Troubleshooting¶
| Symptom | Likely cause |
|---|---|
Client ID and Client Secret must be provided... (AuthError) |
DORY_CLIENT_ID / DORY_CLIENT_SECRET not set, and none passed to DoryClient(...) |
Failed to retrieve access token (AuthError) |
Wrong client id or secret; the token endpoint could not be reached, or did not answer within DORY_HTTP_TIMEOUT (default 10 s); or the app client does not hold every scope listed above. An app client created in the portal holds all five; if yours was created through the API with fewer, create a new one that holds all five |
Access token not found in response (AuthError) |
The address answered successfully with JSON that holds no access token: DORY_COGNITO_DOMAIN points at something that is not the token endpoint. (A successful answer that is not JSON at all surfaces as Failed to retrieve access token instead) |
Failed to retrieve metadata (MetadataError) |
The token was issued, but the API at DORY_API_ROOT_URL could not be reached or answered an error. This is not a credential problem — do not rotate the secret; check the API root and your network path |
You can only read subscriptions you created / You can only delete subscriptions you created (HTTP 403, RuntimeError) |
Another app client in your organization created that subscription; read or delete it with that client's credentials, or manage it from the portal |
Subscription … was not found: it does not exist, has been deleted, or belongs to another organization (SubscriptionNotFound) |
Wrong id, the subscription was already deleted, or it belongs to another organization |