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.
API | Purpose |
---|---|
POST /v1/tokens | Authenticate a user |
HEAD /v1/users | Check if email address registered |
POST /v1/user | Register a new account |
GET /v1/user | Get user details |
PUT /v1/user | Update user details |
GET /v1/user/config | Get user settings |
PUT /v1/user/config | Update user settings |
PUT /v1/user/image | Update user profile picture |
DELETE /v1/user/image | Delete user profile picture |
POST /v1/user/reset | Request a password reset (triggers an email to the registered email address) |
POST /v1/user/verify | Request email validation (triggers an email to the registered email address) |
GET /v1/support | Get support content that has been uploaded through admin APIs |
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.
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.
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).nativelogin
key to see whether users in your country should log-in with email address (type = email
) or mobile number (type = mobilenumber
).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.
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'
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
}
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:
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.
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.
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.
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.
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.
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
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 (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:
API | Purpose |
---|---|
GET /v1/user/profiles | Gets a list of user sub-profiles |
POST /v1/user/profiles | Add 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}/image | Update a user sub-profile image |
DELETE /v1/user/profiles/{profileuserid}/image | Delete 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.
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.