Overview
Dynamic Planner’s Open API uses a robust, two-layer security model combining an API subscription key with OAuth 2.0 (OpenID Connect) access tokens. Every API call requires both:
- Subscription Key — identifies your application to the API gateway.
- OAuth 2.0 Access Token — authorises requests based on the permissions granted to your application and request context.
OAuth flows follow standard OpenID Connect conventions and support both user‑present and service‑account integrations.
API Access Models
Dynamic Planner supports multiple access models through OAuth 2.0. These allow integrations to align with different workflows and operational needs.
1. Fully Automated (Service Account)
- Ideal for continuous, high‑volume automation.
- Runs without user presence using the Client Credentials flow.
- No callback (redirect) URL required.
2. User‑Present API Access
- API usage is tied to an actively signed‑in user.
- Uses the Hybrid Flow (Authorisation Code + ID Token).
- Requires a registered callback (redirect) URL.
3. User‑Based Automation (Time‑Bound Delegation)
- User grants consent once for limited‑duration background automation.
- Suitable for scheduled or batch processing that runs “as the user”.
- Requires a registered callback (redirect) URL.
| Requirement | Recommended Model |
|---|---|
| No user involved | Fully Automated (Service Account) |
| User actively present | User‑Present API Access |
| Background automation on behalf of a user | User‑Based Automation |
Getting Started with Authentication
1. Request Access
To obtain subscription keys and OAuth credentials, submit a request through Get API Access. You will be asked to provide:
- Company name and environments (Test / Production)
- Expected use cases and required API domains
- Preferred OAuth flow and callback (redirect) URL(s)
Dynamic Planner will issue:
- API subscription key(s)
- OAuth client credentials (client ID and client secret)
- Registered callback (redirect) URL(s)
- Scopes following least‑privilege principles
For security reasons, Dynamic Planner will only redirect users to callback URLs that have been explicitly registered. Requests using an unregistered or mismatched URL will be rejected.
Subscription keys are typically provided by Dynamic Planner for each environment, such as development and production. You will receive the appropriate key as part of the onboarding process.
2. Configure Your OAuth Client
Authorise endpoint:
https://identity.distribution-technology.com/identity/connect/authorize
Token endpoint:
https://identity.distribution-technology.com/identity/connect/token
Supported flows: Hybrid (user‑present) or Client Credentials (service account).
Callback (Redirect) URL
A callback URL (also called a redirect URI) is an endpoint in your application that receives the OAuth authorisation response after the user successfully signs in.
Callback URLs are required for all user‑present OAuth flows and are not used for client‑credentials (machine‑to‑machine) integrations.
You do not need to implement OAuth from scratch. Most common programming languages and frameworks provide established OAuth 2.0 / OpenID Connect libraries that handle redirect handling, token exchange, and validation.
Example: Authorisation request
GET https://identity.distribution-technology.com/identity/connect/authorize
?client_id=your_client_id
&response_type=code
&scope=openid profile crm.read
&redirect_uri=https://yourapp.example.com/auth/callback
&state=xyz123
Example: Callback received by your application
GET https://yourapp.example.com/auth/callback
?code=SplxlOBeZQQYbYS6WxSbIA
&state=xyz123
The state parameter is optional for Dynamic Planner OAuth
integrations. However, where supported, it is recommended as a best
practice to protect against cross‑site request forgery (CSRF).
If a state value is included in the authorisation request, your
application should validate it when handling the callback. The returned
authorisation code must then be exchanged with the token
endpoint to obtain an access token.
Example: Exchanging the authorisation code for an access token
POST https://identity.distribution-technology.com/identity/connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=your_client_id
&client_secret=your_client_secret
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https://yourapp.example.com/auth/callback
The token endpoint returns an access_token, which must be sent
as a bearer token when calling the Open API.
3. Call the API
Include both the bearer token and the subscription key with every request:
GET https://open-api.dynamicplanner.com/crm/v1/clients
Authorization: Bearer <access_token>
Ocp-Apim-Subscription-Key: <subscription_key>
Accept: application/json
When integrating with OAuth, common issues include using an unregistered
redirect URL, sending an expired access token, omitting required request
headers, or assuming parameters such as state are mandatory
in all cases. Always follow the flow issued during onboarding and handle
authentication errors defensively.