Skip to content

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
  1. Token. On construction, DoryClient sends one request to the token endpoint (DORY_COGNITO_DOMAIN with /oauth2/token appended): HTTP Basic auth with client_id and client_secret, grant_type=client_credentials, and a scope parameter naming the five scopes in the next section. The request is bounded by DORY_HTTP_TIMEOUT (default 10 seconds).
  2. API calls. The token goes out as Authorization: Bearer … on every API call — the metadata read at construction, then subscribe(), list_subscriptions(), get_subscription() and unsubscribe(), and wait_until_ready() when its wait runs out and it asks the API.
  3. 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.
  4. 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:all and appclients/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:all is the only broker scope the SDK requests. It never asks for rabbitmq/write:all, rabbitmq/configure:all or rabbitmq/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