The DJfindr API has two ways in, one for each part of it.
| API | How to get access |
|---|---|
| Public API | An API key from the developer portal. Any developer, DJ or client account can create keys, free on every plan. |
| Management API | Sign in with DJfindr (OAuth): you register your app in the developer portal, your app sends the person to DJfindr to approve it, and it gets an access token. See Register an app and Management API. |
API keys
A key looks like djf_live_ followed by 64 letters.
Authorization: Bearer djf_live_...Create a key at djfindr.com/developers/dashboard.
Developer accounts sign in with an emailed code. DJ and client accounts log in
with their DJfindr account, with their usual password, provider or two-factor
authentication (Log in with your DJ or client account). Accept the terms,
then create a key. The API is free to use with a Powered by DJfindr link
wherever you show catalog data; the portal has copyable snippets.
Every key carries scopes (what it may do) and an optional expiry (30 days
to a year, or never).
| Account | Scopes a key can hold |
|---|---|
| Developer account | Chosen when you create the key. The public catalog needs catalog:read; the Management API's GET /me, which answers who the key belongs to, needs account:read. |
| DJ or client account | catalog:read only: the Public API. |
GET /me is the only part of the Management API a key can reach: everything
else under /me needs a person's OAuth access token (see
Management API), and a key gets 403 with
code: "oauth_required" there. A write scope includes reading the same things.
Give a key only the scopes it needs.
Your key is shown once, when it is created, and is stored only as a hash
afterwards. Neither we nor you can recover the value later: if you lose it,
rotate it in the portal and you get a new one with the same name, scopes
and expiry. You can also disable a key (and enable it again) without deleting it.
Treat the key as a secret. Do not embed it in client-side code or a mobile
app, where anyone can read it out of the bundle; keep it server-side, in your
platform's secrets store or an environment variable, and have your server call
the API on your users' behalf.
Make all requests over HTTPS. Requests without a valid key fail with 401.
curl https://api.djfindr.com/prod/v1/public/djs?occasion=wedding \
-H "Authorization: Bearer djf_live_..."Why a request is refused
A 401 means the key was missing, unrecognised, expired, disabled or
deleted. The response is identical in every case, deliberately: an
unauthenticated caller learns nothing about which one applies.
A 403 means the key is valid but does not hold the scope that part of the
API needs (the error names it), or the account it belongs to cannot use the
API right now. On the Management API it also means an API key was sent where
only an OAuth access token is accepted (code: "oauth_required"), or that the
access token belongs to a DJ whose plan does not include third-party apps
(code: "plan_required"): a DJ connects a third-party app on the Platinum
plan, and until then the same token reads only the Public API.