DDM HelpAuthentication
Every request carries an API key in the Authorization header:
Authorization: Bearer ddm_3f9a1c2b7d4e8f60_Qm9vZ2xlLUtleS1FeGFtcGxlLU5vdC1SZWFsLTEyMzQ1
Keys are created by an administrator in the CMS under Settings › API access.
Creating a key
Open Settings › API access
and click New key.
Give it a name
that says which system uses it, e.g. PIM export. The name appears in the key list and in the audit log.
Choose what it may do
- Read – take documents, categories and files out. Every key may read.
- Write – push documents in, and change and delete documents and categories. A writing key needs a push source (see Pushing documents).
Choose what it sees
- Released content only – what readers see in the app: no archived documents, and with Distribute only after approval switched on, no unapproved ones. Files can only be downloaded if they may leave the app (Sharing allowed). This is the right choice for an export to a website or a shop.
- Everything in Documents – what the person sees in the CMS, drafts included. A key that writes always sees everything.
Choose as whom it acts
The key has this person's permissions: an administrator's key sees everything, while an editor's key sees only the categories that editor may see. By default the key acts as you. For an integration it is often better to create a dedicated user, give them exactly the categories the integration needs, and let the key act as them.
Set an expiry date, if you like
After that date the key stops working.
Copy the key
It is shown once. DDM keeps only a fingerprint (a hash) of it, so nobody can show it to you again, not even an administrator. If you lose it, create a new key and revoke the old one.
When a key stops working
A request is refused with 401 unauthorized if the key is missing, malformed, unknown, revoked or expired, or if the organisation has been switched off. All of these give the same answer, so a guessed key learns nothing.
A request is refused with 403 forbidden if:
- the key lacks the permission (e.g. a read-only key tries to push), or
- the person it acts as has been blocked or has left the organisation – the key stops with them, or
- the organisation's plan no longer includes the API.
Old CMWS keys
An organisation moved over from the old Document Distribution Manager keeps the keys of its CMWS interface. They are listed as Old CMWS key, act as the person named at the move, write through a push source of their own, and work only at /api/cmws/v1 – see Moving from CMWS. They travel in the address, where many logs keep them: replace one with a new key when the integration allows – a new key is taken in ?apikey= there too.
Rate limit
A key can make 600 requests per minute. More are refused with 429 rate_limited and a Retry-After header saying how many seconds to wait.
Keeping keys safe
- Treat a key like a password. Put it in the other system's secret store or an environment variable, never in source code or a URL.
- Use one key per system, so revoking one does not stop the others.
- Give a key no more than it needs: read-only for an export, and an acting person with only the categories required.
- Keys start with
ddm_. This helps secret scanners (such as GitHub's) recognise a leaked key. - Rotate by creating a new key, switching the system over, then revoking the old one under Settings › API access. Revoking takes effect from the next request.
Every change made through a key is recorded in the audit log under the person the key acts as. Creating and revoking keys are recorded too.