API - Authentication

Every request you make carries a bearer token:

Authorization: Bearer YOUR_TOKEN

There are two kinds, depending on who's doing the calling.

Service tokens

A service token (dpg_api_live_…) stands for an integration rather than a person. It's account-wide, you make it in the admin under Settings → API → API Tokens, and you send it straight through as a bearer token with no sign-in step. This is what you want for a server, a script or an automated workflow.

What a service token can do is set by its scopes:

Scope What it grants
api.images.read Read images, sets, keywords and facets
api.images.write Edit image fields
api.images.delete Delete images
api.keywords.write Add, remove and rename keywords
api.ratings.write Set ratings
api.metadata.write Edit metadata, crop, alt-text and credits
api.sets.write Create and edit sets, membership, order and go-live
api.upload Upload images
api.download Resolve downloads and build archives

Give a token only the scopes it needs. You can also set an expiry, restrict it to certain IP addresses, and cap the size of a request.

GET /v1/me shows you a token's live capabilities. It's the quickest way to check it's scoped the way you meant.

User tokens

When your software is acting for a signed-in person, like a mobile or desktop app, use the sign-in flow instead. It hands out short-lived access tokens tied to that user's own permissions.

  1. POST /v1/auth/sign_in with login, password and a device descriptor.
    • If the user has two-factor turned on, you'll get an mfa_token back; finish the sign-in with POST /v1/auth/mfa and their current authenticator code.
    • Otherwise you'll get a refresh_token and the accounts they can work on.
  2. POST /v1/auth/token with the refresh_token and an account_uuid gives you a 15-minute access token for that account.
  3. When it runs out, call /v1/auth/token again with your latest refresh_token. The refresh token changes every time you use it, so always keep the newest one.

Refresh tokens are single-use, and they rotate on every call. If an old one turns up again we treat it as a sign the token has leaked and end that device's session, so only ever store the most recent one.

Signing in is rate limited, both per IP address and per login, and a throttled request comes back as 429 with a Retry-After header.

Which one should you use?

For an integration or an automated workflow, use a service token. It's simpler, and it's what the rest of these guides assume. For an app that people log into, use the user flow.

Article short link: https://dpg.support/aasr
Last updated: