You can let users sign into your website using their accounts. This document describes what you need to do to configure these capabilities.
You should have a basic understanding of OAuth 2 with an authorization code. See the official OAuth page for more information.
It's also worth being familiar with the Audiogum Platform Documentation which describes all of the APIs that you'll use to enable sign in.
Step 1. only has to happen once for each user that you want to be able to sign in to your site.
Step 2. will happen every time they want to sign in.
User accounts can have 'abilities'. An ability is a piece of configuration that is owned by an OEM administrator - which you will be as owner of the website.
You can add whatever relevent material you need to a user, and once they're signed in to Audiogum you'll be able to read the abilities from the user's configuration.
For example, you could use the following to indicate that a user cannot change anything from within the application.
{"roles":["reader"]}
Again: the content of the abilities section is entirely up to you - choose whatever data format will allow you to distinguish non-users and users, and if needed, the different capabilities that your users can have in your application.
The request to change the abilities of a user should be similar to the following:
POST https://api.audiogum.com/v1/users/<id>/abilities
Authorization: <basic auth based on your admin client_id and client_secret>
Accept: application/json
Content-Type: application/json
{"roles":["reader"]}
Where <id>
is the ID of the user that you want to modify.
You can find <id>
using GET /v1/user
once the user has signed in.
To sign a user in you'll have to perform the following steps:
Create a login URL with the following form:
https://api.audiogum.com/v1/authorize?client_id=<client-id>&scope=read_userprofile&response_type=code
Replace <client-id>
with your client ID.
When someone asks to sign in to your site, you'll have to redirect them to the URL that you created in stage 1. If your application is using Javascript it's common to use window.location.replace
to change the URL of the browser. If you aren't using Javascript, the sign in link can point directly to Audiogum.
Once the user has signed in to Audiogum they'll be redirected back to your site, to the URL that was configured when you created your client account. The URL will contain a query parameter code
which you should store.
Abilities are store in the user's configuration. To get the configuration make a call to the Audiogum user configuration endpoint.
Please see the Platform Documentation site for full details, but it should be enough to do the following
GET http://api.audiogum.com/v1/user/config
Authorization: Bearer <token>
Accept: application/json
Replace <token>
with the token that you received in step 3. The response will be a JSON structure that might have a key abilities
which will contain the structure that you added to the user in the first section of this document.
If the user doesn't have an abilities
key then you haven't authorised the user to sign in to your site.
Examine the contenets of the abilities
structure, and use that to allow access to your website. For example, if you use roles for configuration, don't allow read-write access to a user with only a reader role.
+-------+ +---------+ +-----------+
| User | | Website | | Audiogum |
+-------+ +---------+ +-----------+
| | |
| Sign in | |
|------------------>| |
| | |
| Redirect URI | |
|<------------------| |
| | |
| Sign in | |
|---------------------------------------->|
| | |
| | Redirect URI |
|<----------------------------------------|
| | |
| Access token | |
|------------------>| |
| | |
| | Get abilities |
| |-------------------->|
| | |
| | abilities |
| |<--------------------|
| | |