User Accounts

The Audiogum platform provides various secure account APIs, allowing you to securely host user account data with us or utilise our platform whilst keeping your user data private and integrating with our Shadow Account APIs.

APIPurpose
POST /v1/tokensAuthenticate a user
HEAD /v1/usersCheck if email address registered
POST /v1/userRegister a new account
GET /v1/userGet user details
PUT /v1/userUpdate user details
GET /v1/user/configGet user settings
PUT /v1/user/configUpdate user settings
PUT /v1/user/imageUpdate user profile picture
DELETE /v1/user/imageDelete user profile picture
POST /v1/user/resetRequest a password reset (triggers an email to the registered email address)
POST /v1/user/verifyRequest email validation (triggers an email to the registered email address)
GET /v1/supportGet support content that has been uploaded through admin APIs


Shadow Accounts

If you have an existing authentication and user account system of your own, the Audiogum platform supports "shadow accounts", i.e. we allow you do the user authentication and pass us a consistent, unique ID that represents your user within our platform. We anonymise the identifier passed to us for the user by consistently transforming it into a uuid internally - this allows you to choose from a range of identifiers - e.g. your user account ID, an email address, etc.

In this case, see details of how to authenticate the user.


Config

Before you begin creating user accounts, your device will need to authenticate with our API. You may also want to check the configuration that our API returns before you decide which sign-up/log-in options to present to your user.

curl -vX GET --header 'Authorization: Bearer <device token>' 'https://api.audiogum.com/v1/config'

The configuration in the response is different for each country.

  • Check the loginproviders key for a list of providers that are supported in your country (e.g. Google and Facebook are supported only outside China; WeChat is supported world-wide).
  • Check the nativelogin key to see whether users in your country should log-in with email address (type = email) or mobile number (type = mobilenumber).

Login with email address and password

Create account

To register a new user using their email address and a password,

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Basic <clientid:secret as base64>' -d '{ \
   "deviceid": "<deviceid>", \
   "firstname": "string", \
   "lastname": "string", \
   "scope": "all", \
   "email": "user@example.com", \
   "password" : "abcd1234"
 }' 'https://api.audiogum.com/v1/user'

You'll receive an access token and refresh token in the response. An HTTP Status code of 409 indicates there is already an account with that email address registered.

Returning user

Users who have already signed up can log-in like:

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Basic <clientid:secret as base64>' -d '{ \
   "deviceid": "<deviceid>", \
   "grant_type": "password", \
   "scope": "all", \
   "email": "user@example.com", \
   "password" : "abcd1234"
 }' 'https://api.audiogum.com/v1/tokens'


Update user details

PUT /v1/user

Try this in our API explorer. (All fields are optional) Secured with OAuth2 bearer access_token.

Authorization: Bearer xxxxxxxxxxx
Content-Type: application/json
{
 "firstname":"Something",
 "lastname":"Something",
 "countrycode":"cn",
 "password":"new-password",
 "crmemailallowed":true,
 "crmpushallowed":true,
 "locationallowed":false
}

The response merges the updated fields with the existing data and returns non-sensitive updated information.

200 OK
{
  "userid": "uniqueuserid",
  "email": "something@somewhere.com",
  "firstname":"Something",
  "lastname":"Something",
  "countrycode":"cn",
  "crmemailallowed":true,
  "crmpushallowed":true,
  "locationallowed":false
}


Federated Log-in

Audiogum allows user's to log-in via federated identity providers such as Google, Facebook and WeChat. Your app should call /v1/config to determine which of these providers is available in the user's country. The config data you receive will also indicate what scope should be requested when using the identity provider's SDK.

Before you integrate a federated identity provider into your application, you'll need to contact Audiogum support and provide:

  • iOS bundle ID
  • Android package name
  • Android class name (of main activity)
  • Android key hash for Facebook
  • Android signing certificate fingerprint (SHA1)

We use these details to configure your app's access, and once we have this information we'll provide the necessary keys and files to allow your app to use the Google/Facebook/WeChat SDKs.

Log-in with Google

You can let your users log-in with Google with two simple steps:

First, acquire an authorization code from Google using the Google Sign-In SDK for Android or the Google Sign-In SDK for iOS. Next, pass the Google authorization code to the Audiogum API to log-in:

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Bearer <device token>'  -d '{ \
   "response_type": "token", \
   "scope": "all", \
   "code": "4/n0Il8u-lBOmKwW71Wmw21deH2bjM1k..." \
 }' 'https://api.audiogum.com/v1/login/providers/google/complete'

If this Google user has not logged-in in the past, we'll create an Audiogum account for them. You'll receive an Audiogum access token and refresh token for the user in the response.

Log-in with Facebook

You can let your users log-in with Facebook with two simple steps:

First, acquire a user access token from Facebook using the Facebook Login SDK. Next, pass the Facebook user access token to the Audiogum API to log-in:

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Bearer <device token>'  -d '{ \
   "response_type": "token", \
   "scope": "all", \
   "token": "EAAX8nRJxuWim3Cit9Ez74hgWCvYXZAuD..." \
 }' 'https://api.audiogum.com/v1/login/providers/facebook/complete'

If this Facebook user has not logged-in in the past, we'll create an Audiogum account for them. You'll receive an Audiogum access token and refresh token for the user in the response.

Log-in with WeChat

You can let your users log-in with WeChat with two simple steps:

First, acquire an authorization code from WeChat using the WeChat Open Platform SDK. Next, pass the WeChat authorization code to the Audiogum API to log-in:

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Bearer <device token>'  -d '{ \
   "response_type": "token", \
   "scope": "all", \
   "code": "0211g1mZ0bSOH22pZ..." \
 }' 'https://api.audiogum.com/v1/login/providers/wechat/complete'

If this WeChat user has not logged-in in the past, we'll create an Audiogum account for them. You'll receive an Audiogum access token and refresh token for the user in the response.

Authentication errors

On completing a federated login via POST to /v1/login/providers/{provider}/complete the app should receive an Audiogum authorization code, however in some circumstances the login will fail and the app will receive an error and error_description instead. The suggested action for each of the possible errors is as follows:

  • error=access_denied - The user did not grant access to the required information from the login provider (e.g. they granted no access by clicking the 'Cancel' button instead of logging in, or they removed required permissions before authorizing the application). The app must explain this failure clearly to the user. The app should then invite the user to begin the login process again and present the standard set of login options.
  • error=invalid_request - This indicates a client application bug or suspected tampering with submitted values, this should be treated as an unexpected error. The app should invite the user to begin the login process again and present the standard set of login options.
  • error=conflict - This indicates that the user already has an account, and they have used the wrong method of login. This error will be accompanied by an existingprovider field which will indicate the login method this user should use. The app must explain this failure clearly to the user. The app should then invite the user to begin the login process again and present the standard set of login options.

If the app receives any other error value this should be treated as an unexpected service error. The app should invite the user to begin the login process again and present the standard set of login options.


Login with mobile number

Create account

To register a new user using only their mobile number,

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Basic <clientid:secret as base64>' -d '{ \
   "deviceid": "<deviceid>", \
   "firstname": "string", \
   "lastname": "string", \
   "scope": "all", \
   "mobilenumber": "+867788909809"
 }' 'https://api.audiogum.com/v1/user'

HTTP/1.1 204 No Content

The user will receive a text message containing a 6-digit authorization code. You should ask them to enter the code and when they do you can log-in like:

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Basic <clientid:secret as base64>' -d '{ \
   "deviceid": "<deviceid>", \
   "countrycode": "<your countrycode>", \
   "grant_type": "sms_authorization_code", \
   "mobilenumber": "+867788909809",
   "code": "293857" \
 }' 'https://api.audiogum.com/v1/tokens'

You are now logged in.

Make sure you include a button or similar in your UI that allows the user to 'resend' the code (in case they don't receive, or lose, the first SMS). If the user asks for a second authentication SMS then you can request another like:

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Basic <clientid:secret as base64>' -d '{ \
   "scope": "all", \
   "mobilenumber": "+867788909809" \
 }' 'https://api.audiogum.com/v1/login/sms'

HTTP/1.1 204 No Content

Returning user

For users that have previously registered via SMS and want to log-in, you can request a 6-digit SMS authorization code like:

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Basic <clientid:secret as base64>' -d '{ \
   "scope": "all", \
   "mobilenumber": "+867788909809" \
 }' 'https://api.audiogum.com/v1/login/sms'

HTTP/1.1 204 No Content

and then log-in like:

curl -vX POST --header 'Content-Type: application/json' --header 'Authorization: Basic <clientid:secret as base64>' -d '{ \
   "deviceid": "<deviceid>", \
   "grant_type": "sms_authorization_code", \
   "mobilenumber": "+867788909809",
   "code": "293857" \
 }' 'https://api.audiogum.com/v1/tokens'


User Sub-Profiles

User sub-profiles (a.k.a "personnas") allow you to offer the feature to your users where taste profiles can be segregated from a main user account that controls content service access. For example, a user may wish create a "kids" sub-profile to play child-friendly content or allow access to a friend or other family member. By using the user sub-profiles, the main account's profile is not "polluted" by the actions taken within the sub-profile.

The following APIs manage the user sub-profiles:

APIPurpose
GET /v1/user/profilesGets a list of user sub-profiles
POST /v1/user/profilesAdd a new user sub-profile by giving a firstname and lastname
GET /v1/user/profiles/{profileuserid}Get a user sub-profile
PUT /v1/user/profiles/{profileuserid}Update a user sub-profile
DELETE /v1/user/profiles/{profileuserid}Delete a user sub-profile
PUT /v1/user/profiles/{profileuserid}/imageUpdate a user sub-profile image
DELETE /v1/user/profiles/{profileuserid}/imageDelete a user sub-profile image

Once user sub-profiles have been created, apps can use personalisation and playback APIs on behalf of the sub-profile by sending the profileuserid in a profileuserid header. Note: only a subset of Audiogum APIs respect the profileuserid header - these are noted in the API explorer descriptions.


Support content

The API allows you to create structured help and support data that can be displayed in your apps: GET /v1/support

Try this in our API explorer.

Secured with OAuth2 bearer access_token.

Authorization: Bearer YmVhcmVyIHRva2VuIGdvZXMgaGVyZQ==
GET /v1/support

The response is a json object containing the support content uploaded through the admin APIs.