Skip to main content

Credentials

This page covers how credentials travel on an API request. For where your credentials come from, how to generate short-lived ones for client devices, and which credentials to test with, see Apps and Credentials.

Every endpoint requires credentials. There is no anonymous access, and requests must be made over HTTPS. Both your consumer pair and any access pair you mint work the same way here.

Authenticating a request​

HTTP Basic authentication, with the token as the username and the secret as the password.

curl -sS -u "$FEEDFM_TOKEN:$FEEDFM_SECRET" https://feed.fm/api/v3/station

That produces an Authorization header. X-Authorization carries an identical value and exists for browser and SDK environments that cannot set Authorization directly:

Authorization:   Basic base64(token:secret)
X-Authorization: Basic base64(token:secret)

Send one or the other, never both. X-Authorization is applied first and replaces any Authorization on the same request.

A request with missing or invalid credentials returns HTTP 401, the header WWW-Authenticate: Basic realm="Feed.fm", and a badCredentials (code 5) error body.

Errors worth handling​

Minting and revoking access credentials is done with POST /access_token and DELETE /access_token/{token}, both authenticated with your consumer credentials. Those two routes report the same condition differently, which is easy to miss when writing error handling:

  • Presenting an access token to POST /access_token returns 403 forbidden.
  • The same condition on the DELETE route returns 404 missingObject.

Handle both. A consumer may only revoke access tokens it created; revoking one belonging to a different consumer returns 403 forbidden.

For the full error table, see the API reference.

One client id, one device at a time​

A client id identifies a single listener with a single play queue and history. Two devices calling under the same client id at the same time interleave their reservations and reports against that one shared queue. Plays get started that the other device is holding, completes land against the wrong song, and the reported history stops matching what was actually heard. Give each device its own client id or ensure that two devices don't use the same client id at the same time.

Values longer than 23 characters are silently truncated, which only matters if you supply your own client id rather than using the one POST /session mints. Two ids that differ only after the 23rd character are the same listener.

Rate limits​

Error throttling is counted and applied per client, not per app. A client that gets ten errors within 60 seconds of the first is throttled (code 22), with HTTP 429 on POST /play, until five minutes after the first error. Other clients under the same credentials are unaffected, so one misbehaving device cannot silence an app.

The usual cause is a client that keeps calling POST /play on a station that has run out of music. Stop requesting from a station once it answers noMoreMusic.