---
title: "Authentication"
canonical_url: https://support.digitalphotogallery.com/articles/article/1667f446-73dd-43ab-b737-de59974d8845
short_url: https://dpg.support/aasr
category: "API"
locale: en
updated_at: 2026-07-03T17:22:31Z
source: Digital Photo Gallery Support
---

# 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.

> 💡 **Tip:** `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.

> ⚠️ **Warning:** 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**.