Authentication

To use the Skyfish API you authenticate once to get an auth-token, and then send that token on every request.

Username and password with HMAC

POST /authenticate/userpasshmac exchanges the user’s username and password, together with a valid HMAC, for an auth-token. You find your API key and secret on your API keys page.

Payload

Field	Description
`username`	Username
`password`	Password connected to the username
`key`	API key
`ts`	Current UNIX timestamp
`hmac`	HMAC hash. Must be lower case.

The HMAC is HEX(HMAC-SHA1(secret, apikey + ":" + ts)). The timestamp must be within 60 seconds of the current time, otherwise the request is rejected with 400.

Returns

Field	Description
`token`	An auth-token for request authorization
`type`	The type of token. Always `1` for a user, meaning that the auth-token is bound to that user
`ownerIdentifier`	The user ID in Colourbox
`validUntil`	When the auth-token expires (UNIX timestamp)

Example

With the API key mykey, the secret mysecret and the timestamp 1383307501:

echo hash_hmac('sha1', 'mykey:1383307501', 'mysecret');
// 84b252e61bd800f33fcd58fb006a0f01377ec979

curl -d '{"username":"palle","password":"bilka","key":"mykey","ts":1383307501,"hmac":"84b252e61bd800f33fcd58fb006a0f01377ec979"}' \
  https://api.colourbox.com/authenticate/userpasshmac

{
  "token": "b932d2522301db11a33196411bb4b260d9b8d3b5",
  "type": 1,
  "ownerIdentifier": 3232,
  "validUntil": 1384389501
}

Authorizing requests

All authorization is done through the Authorization header:

Authorization: <auth-schema> <auth-params>

The auth-schema defines the method and the auth-params are a space separated list of key=value fields specific to the schema. The Skyfish API supports the CBX-SIMPLE-TOKEN schema, which takes one param, Token:

Authorization: CBX-SIMPLE-TOKEN Token=<auth-token>

Using the token from the example above to fetch a media:

curl -H "Authorization: CBX-SIMPLE-TOKEN Token=b932d2522301db11a33196411bb4b260d9b8d3b5" \
  https://api.colourbox.com/media/42343

Validating a token

GET /authenticate/simpletoken/:tokenString returns the status of an existing token:

{ "TokenStatus": "valid" }

TokenStatus is valid for valid tokens and invalid otherwise.

Password reset

POST /authenticate/userpass/reset requests a new password for a username. It always returns 204, whether the username is valid or not.