Authentication and Authorization

All Audiogum APIs require authorization for access - typically an OAuth2 bearer token to act on behalf of a user or device, but some APIs are secured with HTTP Basic authentication - typically to obtain the bearer token.

You will be issued with a client_id and client_secret for each device or app variant you require to access the APIs - for example the iOS version of your app will have a different set of keys to your Android version; your development versions will have different secrets to your production versions. This allows us to keep your data segregated and to secure your data by rotating keys in a granular way if needed.


User authentication

There are three steps involved in obtaining a bearer token to access APIs - this is modelled on an OAuth2 token grant_type.

  1. Show Authorization UI: The app shows a native sign-in (or registration) form allowing the user to enter their existing credentials, create a new account, or sign in with a federated authentication provider like Facebook or Google.
  2. Validation and Token Exchange:
    1. For users that opt to login using their email address, the app posts the email and password entered to /v1/tokens (for sign-in) or /v1/user (for registration) and will receive access tokens if the details are valid. It is assumed that the app does basic checks on the data - e.g. the email address is valid (e.g. using a Regular Expression) and that for registration, the password has been entered twice to check the user has typed correctly. The app should store this response as the token details returned will include the expiry time and a refresh_token to allow continued access on behalf of the user without the need to sign-in again - see Token Renewal.
    2. For users that opt to login using a federated authentication provider like Facebook, the app must acquire an access token or authorization code using the native client SDK of the federation provider. Once an authorization code or token has been acquired, for example from Facebook, login can be completed by posting to /v1/login/providers/facebook/complete. An Audiogum token can then be acquired via the /1.x/tokens resource using the grant type authorization_code.
    3. Note: The app should call /v1/config to get a list of federated login providers that should be implemented and displayed to the user. These vary by country (e.g. some login providers like QQ and Weibo may be present in China, but others like Facebook and Google may only be available outside China).
  3. Access Secured Resources: The app can then use the token to access the desired user APIs by sending the access_token in the Authorization header of each request - e.g. Authorization: Bearer v1::k0PWZsbtc46216yGHXKahQ==::ur5SojWb0r9ZNHYXDCSfqSUSR240ehpI...

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.

App Authorization Flow sequence diagram

Authorization Flow (native)

See authenticate a user example.


Device authentication

When there is no direct user involved - e.g. before a user has signed into an app or from a device that does not run in the context of a user, we offer "device authentication" based on an OAuth2 client_credentials grant_type. Device tokens have a restricted set of scopes available to them.

1) Obtain Token: POST a deviceid and scope secured with basic auth of client_id:client_secret to get an access_token along with an expiry period. Note that a refresh_token is not returned as there is no need, this call can be made again.

POST /v1/tokens
Content-Type: application/json
Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0
{
 "grant_type": "client_credentials",
 "scope": "read_device",
 "deviceid": "94d8fce730eb4c2d886b2c82a5b16c53"
}

2) Access Secured Resources: The device can then use the token to access the desired APIs by sending the access_token in the Authorization header of each request - e.g. Authorization: Bearer v1::k0PWZsbtc46216yGHXKahQ==::ur5SojWb0r9ZNHYXDCSfqSUSR240ehpI...

Device Authorization Flow sequence diagram

Authorization Flow (device)


Shadow account authentication

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.

The authentication flow uses client_credentials, the same as device authentication, with an extra externaluserid parameter included:

POST /v1/tokens
Content-Type: application/json
Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0
{
   "grant_type": "client_credentials",
   "scope": "read_device",
   "deviceid": "94d8fce730eb4c2d886b2c82a5b16c53",
   "externaluserid": "someuser@example.com"
}


Scopes

The Audiogum API supports the follow OAuth2 scopes that are required when requesting access tokens. The following aliases are available to simplify access and should be used for forward-compatibility:

all gives all user and device API scopes.

device-all gives all device API scopes.

userdevice-all gives all user scopes for delegation to a device with delegated tokens.

ScopeDescription
admin_deviceadminAdmin access to update and delete devices
admin_deviceviewAdmin read-only access to view devices
admin_firmwareAdmin access to add, update and delete firmware information
admin_releasesAdmin access to add, update and delete app release information
admin_supportAdmin access to add, update and delete support information
admin_useradminAdmin access to update and delete users
admin_userviewAdmin read-only access to view users
delegateOnly users can delegate, this scope is never used but differentiates 'all' from 'userdevice-all'
playlistingGenerate a one-off playlist
read_deviceRead device details
read_devicediscoveryGet devices for a user with remotecontrol tokens
read_playlistsRead playlists
read_releaseRead app release details
read_usercatalogRead user catalog (user-auth required)
read_userprofileRead user profile (user-auth)
searchSearch for audio
signinBasic access
speechUnderstand spoken instructions, search, create playlists and control a speaker
write_deviceWrite device details
write_eventsSend analytics events
write_playlistsWrite user playlists (user-auth required)
write_sampleStore audio samples (for example for wakeword storage)
write_usercatalogWrite user catalog (user-auth required)
write_userprofileWrite user profile (user-auth required)

Examples

The Audiogum API offers many ways to create user accounts and log-in. The detailed examples below show exactly how to craft requests for each kind of log-in, and can be used as a reference alongside our API Explorer and Authentication documentation.

Pre-requisites

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.

Device authentication

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

Config

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 or mobile number.

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.

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'

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'

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.


Refreshing Tokens

Access tokens have a limited lifetime. The expiry time (expires_in) is provided in the response body alongside the token itself. Once a token has expired any request made that uses it will fail with an HTTP 401 response.

In the case of user authentication tokens, also provided in the token response body is a refresh_token. This can be used to request a new access token without the user having to re-approve access. This enables the API to manage token lifetimes more effectively and improves security by making it easier to revoke access tokens where an app is found to be misusing data or if the user decides they no longer wish to allow an app to access their data.

To use the refresh_token to obtain a new token, POST to /v1/tokens secured with basic auth client_id:client_secret including the refresh_token in the body as shown.

POST /v1/tokens
Content-Type: application/json
Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0
{
   "grant_type": "refresh_token",
   "refresh_token": "v1::vA/YkIi..."
}

The response will contain new access_token, refresh_token and expires_in values to replace previous.

Note that refresh_token is not required for device authentication tokens because the device may request a new token without any user-provided secrets.