OAuth 2.0
Authorization Code with PKCE for loopback clients; Device Authorization Grant for hosts that cannot bind localhost; exchange at `/api/oauth/token`, call `/api/v1` with the access token.
Third-party and official clients use OAuth 2.0. Authorization Code + PKCE is the default for desktop apps that can open a browser and listen on a loopback redirect. Device Authorization Grant is used when the host cannot bind 127.0.0.1 (Photoshop UXP). Confidential clients with a client_secret are supported for server-side apps registered by workspace owners.
Public client flow (Lightroom / Capture One)
1. Plugin opens browser → GET /oauth/authorize?client_id=…&code_challenge=…&redirect_uri=…&scope=…
2. User logs in (if needed) → consent screen (scopes + workspace)
3. Redirect to loopback → ?code=…
4. POST /api/oauth/token (code + code_verifier) → access + refresh tokens
5. API calls → Authorization: Bearer aist_at_…
Desktop clients use a loopback redirect (e.g. http://127.0.0.1:54321/callback) registered on the OAuth application. Public clients do not embed a client_secret.
Device Code flow (Photoshop)
1. Plugin POST /api/oauth/device_authorization → device_code + user_code + verification_uri
2. Plugin opens browser → /oauth/device (user enters code, signs in, consents)
3. Plugin polls POST /api/oauth/token (grant_type=urn:ietf:params:oauth:grant-type:device_code)
4. On approval → access + refresh tokens
5. API calls → Authorization: Bearer aist_at_…
See Photoshop for the install and Connect walkthrough.
Endpoints
| Method | Path | Role |
|---|---|---|
| GET | /oauth/authorize | Consent page (Authorization Code + PKCE) |
| GET | /oauth/device | Device Code verification / consent UI |
| POST | /api/oauth/device_authorization | Start Device Authorization Grant |
| POST | /api/oauth/token | Exchange code, device_code, or refresh token |
| POST | /api/oauth/revoke | Revoke access or refresh token |
Platform vs custom clients
| Tier | Who registers | Dashboard |
|---|---|---|
| Platform | ArtInStack ops (Directus oauth_clients) | User sees app under Connected apps after consent |
| Workspace | Workspace owner | Settings → Developer → OAuth applications |
Official Lightroom, Capture One, and Photoshop use platform-owned client rows. Photographers do not register them themselves.
Refresh
Use the refresh token at /api/oauth/token before the access token expires. Serialize refresh in the client to avoid races during concurrent uploads.