The Management API accepts OAuth access tokens only. Your application redirects the person to DJfindr, the person signs in and approves the scopes your application requests, and your application exchanges the returned code for an access token.
DJfindr implements OAuth 2.1 with the authorization code grant and PKCE (S256).
Your application needs a client_id: register it as an app in the developer portal (see Register an app). A confidential app also receives a client secret, which it sends to the token endpoint with client_secret_basic.
| Endpoint | URL |
|---|---|
| Authorization | https://djfindr.com/api/auth/oauth2/authorize |
| Token (code exchange and refresh) | https://djfindr.com/api/auth/oauth2/token |
| Server metadata | https://djfindr.com/.well-known/oauth-authorization-server/api/auth |
Authorization flow
- Generate a PKCE code verifier and its
S256code challenge. - Redirect the person to the authorization endpoint with your
client_id,redirect_uri, the requestedscope, astatevalue and the code challenge. - The person signs in to DJfindr and approves the requested scopes.
- DJfindr redirects to your
redirect_uriwith an authorizationcode. - Exchange the code, with the code verifier, at the token endpoint.
- Send the access token on every request:
GET /prod/v1/me HTTP/1.1
Host: api.djfindr.com
Authorization: Bearer djf_at_...Tokens
| Token | Lifetime | Notes |
|---|---|---|
Access token (djf_at_...) | 1 hour | Sent as a bearer token. |
| Refresh token | 30 days | Issued when you request offline_access. Each refresh returns a new refresh token and invalidates the previous one. |
A connection ends when the person revokes it on DJfindr, in Settings > Integrations > Connected apps (DJs) or Settings > Account > Connected apps (clients). Requests with a revoked token return 401.
Scopes
Request only the scopes your application needs. Each endpoint in the reference lists the scope it requires. A :write scope includes the matching :read scope.
| Scope | Grants access to |
|---|---|
account:read, account:write | The person, their account details and plan. |
bookings:read, bookings:write | Requests, offers, events, invitations, clients, reviews, documents and extensions. |
payments:read, payments:write | Payments, payouts and PayLinks. |
calendar:read, calendar:write | Availability, busy blocks and the calendar feed. |
profile:read, profile:write | A DJ's profile, pictures, handle and DJ link. |
content:read, content:write | Mixes, posts, live events and widget domains. |
inbox:read, inbox:write | Conversations and messages. |
integrations:read, integrations:write | Connected calendars and SoundCloud. |
analytics:read | Profile analytics. |
search:read | Search across the person's records. |
catalog:read | The Public API catalog, read with the access token. |
openid, profile, email | The person's identity (OpenID Connect). |
offline_access | A refresh token. |
A file requires the scope of the record it belongs to. See Files.
To add a scope later, send the person through the authorization flow again with the additional scope.
Who can connect
- Client accounts can always connect. A DJ can connect a third-party app on the Platinum plan; without it the token reads only the Public API (
catalog:read) and the person's identity, and the Management API answers403 plan_required. DJfindr staff and developer accounts cannot connect. Every app registered in the developer portal is a third-party app, including a DJ's own; only DJfindr's own apps and the Claude and ChatGPT connectors are not (see Connecting an AI Assistant). - The plan is checked on every request: when the DJ upgrades, your application's next request succeeds without a new approval, and nothing is revoked when the plan lapses. If the plan cannot be read, the request answers
503 unavailable, neverplan_required. - If the account is missing required details (name, date of birth, phone number or acceptance of the Terms), DJfindr collects them before the person approves.
- A person without an account can create a client account during sign-in. DJ accounts are created on DJfindr first.
Errors
| Response | code | Cause |
|---|---|---|
401 | unauthenticated | The access token is missing, expired or revoked, or the app was deleted or turned off. |
403 | oauth_required | An API key was sent where only an access token is accepted. |
403 | plan_required | The person is a DJ whose plan does not include third-party apps. The Public API still answers the same token. |
403 | forbidden | The token lacks the scope the endpoint requires. |
503 | unavailable | The person's plan could not be checked. The request is safe to retry. |
API keys
An API key reaches one Management API endpoint: GET /me, with the account:read scope, which identifies the account the key belongs to. Every other /me endpoint, including every change, returns 403 with code: "oauth_required" for an API key, before anything is read or changed.
Treat tokens as secretsStore access and refresh tokens in your server's secret storage or the platform's secure storage, and never write them to logs. A client secret belongs on a server only.
Rate limits
Requests are limited to 100 per minute for each person and application, in addition to DJfindr's platform limits. A limited request returns 429 with a Retry-After header.